home *** CD-ROM | disk | FTP | other *** search
/ Software of the Month Club 1998 May / Software of the Month Club 1998 May.iso / pc / dos / dtp / sparkl43 / ss.txt < prev    next >
Text File  |  1998-03-03  |  127KB  |  2,747 lines
  1.  
  2.               ---------------------------------------------------
  3.                 -----------------------------------------------
  4.                   -------------------------------------------
  5.                     ---------------------------------------
  6.                       -----------------------------------
  7.                         -------------------------------
  8.                           ---------------------------
  9.                             -----------------------
  10.                               -------------------
  11.                                 ---------------
  12.  
  13.                 SUPER Sparkle (tm)
  14.                       and              by         Rob W. Smetana
  15.                   Menu Magic (tm)                 and Pro~Formance
  16.  
  17.                                 ---------------
  18.                               -------------------
  19.                             -----------------------
  20.                           ---------------------------
  21.                         -------------------------------
  22.                       -----------------------------------
  23.                     ---------------------------------------
  24.                   -------------------------------------------
  25.                 -----------------------------------------------
  26.               ---------------------------------------------------
  27.  
  28.  
  29.  
  30.                       Super Sparkle (tm) & Menu Magic (tm)
  31.  
  32.  
  33.                            **  Version 4.3 (2/98)  **
  34.  
  35.  
  36.       ==================================================================
  37.          Note:  With version 4.x, we introduced SUPER SPARKLE -- a
  38.                 combination of the original Sparkle and Sparkle_2.
  39.                 We also added several NEW features (See What's New).
  40.       ==================================================================
  41.  
  42.  
  43.       ==================================================================
  44.  
  45.          Copyright (C) 1990-1998, Rob W. Smetana  All Rights Reserved
  46.  
  47.  
  48.          132 Alpine Terrace  San Francisco, CA  94117  (415) 863-0530
  49.  
  50.  
  51.          Sparkle, Super Sparkle, Menu Magic, Pro~Formance, P~F, and
  52.                   P-Screen are Trademarks of Rob W. Smetana
  53.  
  54.       ==================================================================
  55.                                                                      
  56.  
  57.  
  58.       ==================================================================
  59.                                    Contents
  60.       ==================================================================
  61.  
  62.            Introduction ...................................... a
  63.            A Summary of Super Sparkle's Main Options ......... c
  64.            What's New ........................................ d
  65.  
  66.            Warranty and Disclaimer ........................... e
  67.            Limited License ................................... f
  68.            Registering INSTANTLY! ............................ g
  69.            Distributing Sparkle .............................. h
  70.  
  71.  
  72.            MENU MAGIC ........................................ MM.1
  73.  
  74.              Using MM ........................................ MM.2
  75.              Creating ".Com" Screens or "Drawing" Menu Screens;
  76.                 Entering File Names .......................... MM.4
  77.              Choosing Colors ................................. MM.6
  78.              More Options .................................... MM.8
  79.  
  80.  
  81.            SUPER SPARKLE ..................................... SS.1
  82.  
  83.              Debugging Batch Files; Sparkle's Error Codes .... SS.3
  84.              Changing the "Text Marker" -- Setting SPM=? ..... SS.4
  85.  
  86.              Sound Effects ................................... SS.5
  87.              Scrolling Bar Menus ............................. SS.6
  88.              Ask (a 3rd menu option, or just to pause) ....... SS.9
  89.              Big! Font ....................................... SS.10
  90.              Quick Print ..................................... SS.11
  91.              Windows ......................................... SS.12
  92.              Pause ........................................... SS.13
  93.              Monitor ......................................... SS.14
  94.              Paint ........................................... SS.16
  95.              Reverse Paint (Reverse Screen Colors) ........... SS.17
  96.                Notes on Paint and Reverse Paint .............. SS.18
  97.              Bright Background Colors ........................ SS.19
  98.              Get Input ....................................... SS.20
  99.                Using "Named Parameters" ...................... SS.33
  100.              Get DOS Version ................................. SS.23
  101.              Viewing Files ................................... SS.24
  102.              Dynamic Prompts ................................. SS.25
  103.              Dark Blue Background Colors ..................... SS.26
  104.              BIG! SCROLLING Messages ......................... SS.27
  105.              Fades (Dramatic Screen Transitions) ............. SS.28
  106.              Broadway Screen Font (VGAs only) ................ SS.29
  107.  
  108.            Appendix I:   A Note on Testing Errorlevels ....... A.1
  109.  
  110.            Appendix II:  Choosing COLOR Numbers .............. A.2
  111.  
  112.            Appendix III: ASCII Codes for Keyboard Characters . A.3
  113.  
  114.            Registering, Ordering ...................  Last 2 Pages  
  115.  
  116.  
  117.       ==================================================================
  118.                                 Introduction                           a
  119.       ==================================================================
  120.  
  121.       Super Sparkle (SS) and Menu Magic (MM) are designed to BOTH add a
  122.       little sparkle to your batch files (and to your day), AND to write
  123.       your batch files for you!
  124.  
  125.        * Super Sparkle offers m-a-n-y options to add sparkle, con-
  126.          venience and hard-to-achieve options to batch files:  menus
  127.          (3 options, including "scrolling bar menus" with mouse support);
  128.          sound effects; tall, scrolling messages; colors (384 of them,
  129.          including "bright background" and "dark blue" colors); windows;
  130.          file viewing; dramatic screen transitions; and more.  Run
  131.          Demo.Bat to see most of Super Sparkle's options in action.
  132.  
  133.        * Menu Magic (MM) is a fill-in-the-blanks menu designer.  Just
  134.          type in your menu options, and MM will WRITE YOUR BATCH FILES
  135.          FOR YOU -- complete with colorful, scrolling bar menus (with
  136.          mouse support)!
  137.  
  138.  
  139.       PLEASE START BY . . .  We urge you to START by running DEMO.BAT --
  140.       the demo batch file.  It demonstrates most of Sparkle's features.
  141.       Once you "see" these features in action, the discussion of each
  142.       option below might make more sense.  NOTE THAT Demo.Bat requires
  143.       several files that come with Sparkle.  It relies heavily on these
  144.       files (especially examples of "executable .COM screens") and
  145.       therefore can't run unless all required files are on the current
  146.       drive/directory.
  147.  
  148.  
  149.       Included are:       SS.Exe     Super Sparkle's main program
  150.                           MM.Exe     Menu Magic's main program
  151.                           SS.Txt     This brief manual
  152.                            *.Bat     Demo batch files (run DEMO!!)
  153.                            *.Com     Examples of         \  created using
  154.                                      "executable          ) P-SCREEN, our
  155.                                      .COM screens"       /  screen-designer
  156.  
  157.                     REGISTER.Exe     To instantly convert Shareware versions
  158.                                      into fully registered versions.
  159.  
  160.       Run:          Demo.Bat      For a demo of all current options.
  161.  
  162.       Purpose:      Sparkle adds a little sparkle to your day or your
  163.                     batch files.  Menu Magic will even create your scrol-
  164.                     ling bar menus and write your batch files for you!
  165.  
  166.       For help:     For help, run Super Sparkle like this:   ss <Enter>.
  167.  
  168.                                                                       
  169.  
  170.  
  171.       ==================================================================
  172.              SUPER Sparkle -- The Latest in the Sparkle Series         b
  173.       ==================================================================
  174.  
  175.       With version 4.x, we introduced SUPER Sparkle.  What's the dif-
  176.       ference between Sparkle and SUPER Sparkle?
  177.  
  178.  
  179.        * Early versions of Sparkle consisted of just Sparkle.Exe.
  180.          When we decided to add options, we created Sparkle_2.Exe.
  181.  
  182.  
  183.        * SUPER Sparkle COMBINES Sparkle and Sparkle_2 -- to make
  184.          Sparkle easier for you to use.  Super Sparkle also ADDS
  185.          more options!
  186.  
  187.  
  188.       As we developed early versions of Sparkle, we tried to keep
  189.       .EXE sizes as small as possible -- so your batch files would
  190.       run as quickly as possible.
  191.  
  192.  
  193.       When we added options, instead of adding them to the original
  194.       Sparkle.Exe, we left it as-is (to keep it small), and created
  195.       Sparkle_2.Exe -- ie., we created the Sparkle "series."
  196.  
  197.  
  198.       But as computers (and hard disks) got faster, it became less
  199.       essential to keep .EXE sizes so small.  And by combining
  200.       Sparkle.Exe and Sparkle_2.Exe into ONE file, we've made it
  201.       easier for you -- you have to manage just one .EXE file.
  202.       This gives you safety and convenience, and makes Sparkle
  203.       easier to use.
  204.  
  205.                                                                        
  206.  
  207.  
  208.       ==================================================================
  209.                Here is A Summary of SUPER Sparkle's MANY Options.      c
  210.       ==================================================================
  211.  
  212.        * SCROLLING BAR MENUS -- WITH MOUSE SUPPORT   Turn ANY text-mode
  213.          screen into a vertical -or- horizontal SCROLLING BAR menu!  Menu
  214.          Magic can even create your scrolling bar menu screens for you!
  215.  
  216.        * ASK   Turn ANY screen (text -or- graphics) into a menu, or use
  217.          Ask just to pause.  You may print a prompt on any row or column,
  218.          in any color.  And you specify which keys are "valid."
  219.  
  220.        * BIG! FONT    Print 8-line-high messages, in any color!
  221.          BIG! SCROLL  Display TALL, SCROLLING messages, in any color,
  222.          using either the "normal" font or a custom "Broadway" font.
  223.  
  224.        * WINDOWS   250+ frame styles; with/without shadows, in any color.
  225.          FILL  Fill areas of the screen with any character in any color.
  226.  
  227.        * QUICK PRINT   Print text anywhere on the screen, in any color.
  228.  
  229.        * SOUND EFFECTS   Over 35 sound effects, from simple to elaborate.
  230.  
  231.        * PAUSE   Pause from 1/3 second to as long as you want.
  232.  
  233.        * MONITOR   Determine what type of display adapter/monitor is active.
  234.  
  235.        * PAINT   Paint areas of the screen, in any color you choose.
  236.  
  237.        * REVERSE COLORS   Reverse colors areas of the screen.  Repeat this
  238.          effect as many times as you like to call attention to areas.
  239.  
  240.        * BRIGHT BACKGROUNDS   Enable or disable bright backgrounds (on
  241.          EGA or VGA monitors).  Use alone, or with Paint and/or Reverse.
  242.  
  243.        * DARKBLUE   On VGA monitors, turn on "dark blue" background colors.
  244.  
  245.        * GET INPUT   Get input from the user, from 1 - 80 characters.
  246.          Sparkle will pass this back to you EITHER in an environment
  247.          variable, or by writing it to a file.  You control:  where on
  248.          the screen to get input, which colors to use, and both the
  249.          maximum AND minimum number of characters to accept.
  250.  
  251.        * PROMPT   Prompt users for a keypress with attention-getting:
  252.          Twirling Batons, Exploding Buttons or a Scrolling Banner.
  253.  
  254.        * VIEW FILE   View ASCII text files of ANY size:  inside any-size
  255.          window on your screen, and in any color you like.
  256.  
  257.        * DOS VERSION   Determine which version of DOS is being used.
  258.  
  259.        * FADES   Select from many, dynamic screen fades (screen transitions).
  260.  
  261.        * BROADWAY Screen Font  On VGA screens, select a tall broadway text-
  262.          mode screen font.  Display both normal & Broadway at the same time!
  263.                                                                        
  264.  
  265.  
  266.       ==================================================================
  267.                                  WHAT'S NEW                            d
  268.       ==================================================================
  269.  
  270.       This summarizes improvements to and changes in Sparkle.  If you
  271.       have an earlier version of Sparkle, pay close attention to this.
  272.       NOTE especially the changes to the Scrolling Bar menu option.
  273.  
  274.       Version    Date   What's New
  275.       -------    ----   ------------------------------------------------
  276.       4.3        2/98   Fine tuning; Changed .DOC to .TXT to avoid confusion.
  277.  
  278.       4.2        9/97   Fixed bug in Register.Exe (thanks Rick P.).
  279.  
  280.       4.0-4.1    8/95   COMBINED Sparkle and Sparkle2 into SUPER SPARKLE.
  281.                         Then we ADDED more options:  Fades, Dark Blue
  282.                         Backgrounds, Big! Scroll and a VGA Broadway font.
  283.                         And Sparkle's "Window" option now lets you FILL
  284.                         areas of the screen with any ASCII character.
  285.  
  286.                         We ALSO added options to:  1. Help you DEBUG
  287.                         batch files (we'll display errorlevels for you);
  288.                         and, 2.  Let you CHANGE the "text marker" --
  289.                         the character you use on the command line to
  290.                         mark the beginning of text.  The "text marker"
  291.                         is normally "/".  But if you need to use "/" in
  292.                         messages, just "SET SPM=?" to change the text
  293.                         marker to anything you like.
  294.  
  295.                         MENU MAGIC:  1. No longer displays a fixed
  296.                         prompt at the bottom of .COM menu screens (we
  297.                         now give YOU the option to print what YOU want);
  298.                         and, 2. No longer <D>raws menu screens by "pad-
  299.                         ding" menu options with ASCII 176 (we now use
  300.                         spaces -- as with .COM menu screens).
  301.  
  302.       3.4-3.5     '94   Refinements, speed-up, fixed mouse slow-down.
  303.  
  304.       3.1        9/92   Added an EXPLODING window option (option -6).
  305.  
  306.       3.0       11/91   Added Menu Magic to create batch files and menu screens.
  307.  
  308.       2.9/2.9c  10/91   Restored color parameter in SCROLLING BAR menus.
  309.                  6/91   You can now repeat sound effects (suggested by
  310.                         Mark Dodd of Texas); tamed the "shareware re-
  311.                         minder" (thanks to V. Baxter of California).
  312.  
  313.       2.8        5/91   Added mouse support to Scrolling Bar Menus.
  314.                         Eliminated "color" parameter in Bar menus.
  315.  
  316.       2.7       11/90   Added "Phone" sound, "Pause" and "Monitor options.
  317.  
  318.       2.4-2.6    9/90   Added 250+ frame styles to the "Window" option.
  319.                         Fixed bug: ASK didn't return 27 if Esc pressed.
  320.  
  321.       2.3        6/90   1st public release.                          
  322.  
  323.  
  324.       ==================================================================
  325.                             WARRANTY & DISCLAIMER                      e
  326.       ==================================================================
  327.  
  328.       This product is provided "AS IS" without warranty of any kind.
  329.       The entire risk as to the results and performance of this pro-
  330.       duct is assumed by you.  We warrant only that any disks we sent
  331.       you are free from physical and workmanship defects under normal
  332.       use and service for a period of 90 days from the date shipped.
  333.  
  334.       Our entire liability, and your exclusive remedy, as to the disk,
  335.       shall be, at our option, to either (1) return the purchase price;
  336.       or, (2) replace disks which don't meet our limited warranty.
  337.       Since you can try "user supported" versions of our programs before
  338.       ordering them, we offer no other warranty beyond that stated
  339.       here.  We'll gladly replace defective disks; but no refunds or
  340.       credits can be issued.
  341.  
  342.       Neither Pro~Formance nor RWS & Associates nor Rob W. Smetana, nor
  343.       any of their officers or employees shall be held responsible for:
  344.       failures of this product to satisfy any needs, damages due to using
  345.       this product, or any effects this program has on you, your business
  346.       or operations.
  347.  
  348.       This product, its manual and any supporting materials may be
  349.       modified or changed from time to time.  They may contain opera-
  350.       tional inaccuracies or typographical errors which may be cor-
  351.       rected by future versions, if any.  Registered users may be
  352.       notified of available updates.
  353.  
  354.                                                                        
  355.  
  356.  
  357.       ==================================================================
  358.                               LIMITED LICENSE                          f
  359.       ==================================================================
  360.  
  361.       *** See the next page for details on registering INSTANTLY. ***
  362.  
  363.       Sparkle is NOT public domain or free software.  It is "user-
  364.       supported" software.  Unauthorized copying or distribution of
  365.       registered versions of this program is strictly forbidden.  See
  366.       the next page for details on REGISTERING INSTANTLY.
  367.  
  368.       UNREGISTERED users of this software are granted a limited license
  369.       to "try out" the user-supported version, on a private, non-
  370.       commercial basis, for the express purpose of determining whether
  371.       it suits your needs.  At the end of this trial period, you must
  372.       either register your copy or stop using it.
  373.  
  374.       * Running Sparkle 15 - 20 different times should allow you
  375.         to decide if it's going to be useful to you.  Therefore
  376.         the "trial period" is set at 30 days.
  377.  
  378.  
  379.       REGISTERED users may make copies of SS.Exe and MM.Exe for
  380.       archival, backup purposes only, and NOT for distribution.
  381.  
  382.  
  383.       SINGLE-USER versions of Sparkle and Menu Magic are licensed like a
  384.       book.  That means you may use them at home, at work, or on your
  385.       laptop -- on as many PCs as you like -- provided they are NEVER
  386.       used on more than one PC at the same time.
  387.  
  388.  
  389.       MULTI-USER/DEVELOPER versions of Sparkle are available.  These
  390.       versions may be used in offices (e.g., to create menuing systems
  391.       many users might take advantage of), on distribution disks (e.g.,
  392.       software vendors create menus for catalogs), etc.  The cost?
  393.  
  394.                                               1-Time Fee
  395.                                               ==========
  396.                 Up to 20 users:                  $ 69
  397.  
  398.                 Unlimited # of users:            $169
  399.  
  400.       ==================================================================
  401.          WARNING:  You MAY NOT use this program in any organization
  402.          or in the conduct of any business activity without a prior
  403.          purchase or license arrangement.
  404.  
  405.          Each copy used must be licensed -- either by an individual
  406.          license, or via a site license or quantity discount agreement.
  407.  
  408.          Sparkle MAY NOT be distributed in any way without a prior,
  409.          written license arrangement.  A single-user license does NOT
  410.          grant the right to give or make it available to others in any
  411.          form, including its use on networked PCs.
  412.       ================================================================== 
  413.  
  414.  
  415.       ==================================================================
  416.                             Registering INSTANTLY                      f
  417.       ==================================================================
  418.  
  419.       You can register for Sparkle in two ways:  1. By mail (use the
  420.       registration form at the end of this manual); or, 2. INSTANTLY by
  421.       phone (with a Visa or MasterCard number).  Regardless of how you
  422.       register, we'll send you latest, registered version of Sparkle.
  423.  
  424.       Shareware versions of Sparkle include REGISTER.Exe.  Run Register
  425.       to convert shareware versions into fully registered versions.
  426.  
  427.       SHAREWARE VERSIONS OF Sparkle and Menu Magic ARE FULLY FUNCTIONING!
  428.  
  429.       They have ALL the features of registered versions, with NO limita-
  430.       tions.  However, shareware versions will periodically remind you
  431.       to register by displaying something like this message:
  432.  
  433.        Reminder:  This is an unregistered version.  Run Register.Exe
  434.  
  435.       This reminder disappears when you run REGISTER (or receive a
  436.       registered version from us).
  437.  
  438.       Early versions of Sparkle had NO built-in reminder, and TWO people
  439.       registered!  Enjoy Sparkle, but remember it is "user-supported."
  440.  
  441.                To register INSTANTLY using REGISTER.Exe . . .
  442.                ==============================================
  443.  
  444.       Step 1:  Be sure that SS.Exe, MM.Exe and REGISTER.Exe are on the
  445.                drive/directory you're logged onto (SS.Exe and MM.Exe
  446.                MUST be).
  447.  
  448.       Step 2:  You'll call us twice at (415) 863 - 0530.
  449.  
  450.                * The first time you call, give us your name, address
  451.                  and Visa or MasterCard number.
  452.  
  453.                * We'll verify the credit card information and add your
  454.                  name to our database so we can notify you about updates.
  455.  
  456.       Step 3:  BEFORE you call us the 2nd time:
  457.  
  458.                * Be sure SS.Exe is on the current drive/directory.  Now
  459.                  run REGISTER.Exe.  REGISTER will ask for the name of
  460.                  the program you want to register.  Type in "ss"
  461.                  (without the quotation marks and without .EXE).
  462.  
  463.                * REGISTER will then print a number.  CALL US when that
  464.                  number is on your screen, tell us what the number is,
  465.                  and we'll give you a DIFFERENT number to type in.
  466.  
  467.                * REGISTER will then ask you to enter your name.  Type in
  468.                  your name and you'll have a fully-registered version.
  469.                                                                        
  470.  
  471.  
  472.       ==================================================================
  473.                             DISTRIBUTING  Sparkle                      h
  474.       ==================================================================
  475.  
  476.       Bulletin board Sysops, clubs and shareware distributors may dis-
  477.       tribute SHAREWARE ("user supported") versions of Sparkle, provided:
  478.  
  479.           *** Your company name IS NOT:   California Freeware ***
  480.                                             American Freeware
  481.                                                   US Freeware
  482.  
  483.           or any company which uses terms like "freeware", "free" or
  484.           "free software" to misrepresent "user-supported" software.
  485.  
  486.       (1) It is distributed in completely unmodified form, and you
  487.           include all these files intact:
  488.  
  489.           SS.Exe, SS.Txt, Demo.Bat, MM.Exe, *.Com, and related files.
  490.  
  491.       (2) You charge nothing other than a "disk distribution fee"
  492.           of up to US $8.00 to cover distribution and handling.
  493.  
  494.       (3) You state YOUR fee is NOT payment or registration for
  495.           OUR software.
  496.  
  497.       (4) You clearly encourage registration by stating that con-
  498.           tinued use justifies sending contributions to the developer.
  499.  
  500.  
  501.                                                                        
  502.  
  503.  
  504.       ==================================================================
  505.                            Using MENU MAGIC  (MM.Exe)               MM.1
  506.       ==================================================================
  507.  
  508.       Menu Magic is a fast, easy-to-use program that helps in 2 ways:
  509.  
  510.         1. Run it, then just "fill in the blanks" to create SCROLLING
  511.            BAR MENUS -- with mouse support, colors, drop shadows, etc..
  512.  
  513.         2. It will then write your batch files for you!
  514.  
  515.       When you've finished running MM.Exe, you can immediately run and
  516.       test the batch file MM created.  But note that as you select menu
  517.       options, your batch file will simply tell you which option you
  518.       selected.  MM can't know what you want done as each option is
  519.       selected.  So it's up to YOU to EDIT this batch file:  jump down
  520.       to the middle/end of the batch file and edit each "option section"
  521.       -- to accomplish what YOU want to happen as options are chosen.
  522.  
  523.       MM is a "front end" to Sparkle.  Use MM to design your menus and
  524.       write your batch file.  When you run this batch file, Sparkle
  525.       takes over and turns your "menu screens" into colorful, scrolling
  526.       bar menus, complete with mouse support!  Using Menu Magic couldn't
  527.       be easier:
  528.  
  529.        * Just type in your menu options (and a title if you like).
  530.  
  531.        * Choose the colors you want.
  532.  
  533.        * Then press a key and MM will write your batch file for you.
  534.          You should then edit this batch file to customize the last
  535.          section -- so that as you choose menu options, your batch file
  536.          does what YOU want it to do.
  537.  
  538.       MM offers TWO ways to display your actual menu screens.
  539.  
  540.        * You can save menu screens as executable ".COM" screens.  Just
  541.          "run" these screens to display your menu screens instantly!
  542.  
  543.          - You can see examples of .Com screens by running Demo.Bat.
  544.            It runs several .Com screens we included with Sparkle.
  545.            We created these .Com screens using our P-Screen program.
  546.            P-Screen offers you more screen-design options than MM can.
  547.            See "More Options" for details.
  548.  
  549.        * Or, if you prefer, MM will write your batch file in such a way
  550.          that Sparkle "draws" your screen -- with colors and shading --
  551.          using Sparkle's "window" and "quick-print" options.
  552.                                                                        
  553.  
  554.  
  555.       TO USE MM:                                                    MM.2
  556.       ==========
  557.  
  558.  
  559.       At the DOS prompt type:    MM <Enter>
  560.  
  561.  
  562.       Creating menus takes 4 simple steps:
  563.  
  564.        1. Enter your menu options (and a title if you want one).
  565.  
  566.        2. Tell MM how to "create" your screen (create an "executable"
  567.           .Com screen, or "draw" your screen using Sparkle's options).
  568.  
  569.        3. Give us a name -- the name of your batch file.
  570.  
  571.        4. Choose colors.
  572.  
  573.  
  574.       When you run MM, a screen like the one below appears.
  575.  
  576.  
  577.       ==================================================================
  578.  
  579.         Title:   ___________________________________
  580.                                                        ┌────────────────┐
  581.        Option:   ___________________________________   │ Working on:    │
  582.                                                        │                │
  583.        Option:   ___________________________________   │    Title       │
  584.                                                        │                │
  585.        Option:   ___________________________________   │                │
  586.                                                        │                │
  587.        Option:   ___________________________________   │ Alt-C = Center │
  588.                                                        │ It is now: OFF │
  589.        Option:   ___________________________________   │                │
  590.                                                        │    Esc = Quit  │
  591.        Option:   ___________________________________   │                │
  592.                                                        │  <F10> = Done  │
  593.        Option:   ___________________________________   └────────────────┘
  594.  
  595.        Option:   ___________________________________
  596.  
  597.  
  598.         Enter a TITLE for your batch file menu (optional), plus up to
  599.         8 menu options (1 - 40 characters each).  You may leave any
  600.         field blank.   Press <Esc> to quit (exit MM and save nothing).
  601.  
  602.       ==================================================================
  603.  
  604.       NOTE:  Press <Esc> (the Escape key) to exit MM to DOS.  Nothing
  605.       will be saved.  So press <Esc> only if you're sure you want to
  606.       cancel whatever you began.
  607.  
  608.                                                                        
  609.  
  610.  
  611.       Using MM (continued)                                          MM.3
  612.  
  613.       Entering a Title
  614.       ================
  615.  
  616.       When MM starts up, it highlights the area beside "Title" (shown
  617.       as "_____" above).
  618.  
  619.       Enter a title if you like -- it's optional.  NOTE:  Titles
  620.       are always centered on the top line of your menu.  Feel free
  621.       to center it on MM's screen if you like.  But you don't have
  622.       to since we'll center it when we later draw your menu.
  623.  
  624.  
  625.       Entering Menu Options
  626.       =====================
  627.  
  628.       Once you enter a title (or not, it's your choice), press <Enter>
  629.       or the Down cursor key.  MM then highlights the first menu "Option."
  630.  
  631.  
  632.        * You can enter up to 8 menu options.  Each may have 1 - 40 char-
  633.          acters.  If you need more than 8 options see "More Options."
  634.  
  635.  
  636.        * MM begins with "centering mode" ON -- when you press <enter>,
  637.          anything you typed in will AUTOMATICALLY be centered.
  638.  
  639.          Press alt-C to turn "centering mode" OFF (or back on again).
  640.          If centering mode is OFF, menu options will appear exactly
  641.          as you enter them.
  642.  
  643.          Toggling centering mode on/off does NOT affect anything you've
  644.          already entered -- just the line you're currently on, and any
  645.          others you type in later.
  646.  
  647.  
  648.        * You can leave any of the 8 options blank.  This lets you
  649.          separate 1 or more options from others by leaving blank
  650.          lines in between.
  651.  
  652.          For example, some people like to separate "Quit" from their
  653.          main menu options.  Or they separate "clusters" of related
  654.          options from other clusters -- with blank space in between.
  655.  
  656.                                                                        
  657.  
  658.  
  659.       Creating <C>om Screens, or <D>rawing Screens                  MM.4
  660.       ============================================
  661.  
  662.       Press function key <F10> when you're done entering menu options.
  663.       (Press <Esc> to quit to DOS without saving what you started.)
  664.       When you press <F10>, MM will ask two questions:
  665.  
  666.        1.  Do you want to save your menu as a ".COM" screen?  Or
  667.            should MM DRAW your menu using Sparkle's options.
  668.  
  669.        2.  What NAME should MM use to create batch file(s)?
  670.  
  671.  
  672.       The first question will actually look like this:
  673.  
  674.          "Do you want to display the menu with a COM screen, or draw
  675.           it using Sparkle's options?  Press <C>om or <D>raw."
  676.  
  677.        * Note that if you press <D>, you're telling MM to write your
  678.          batch file in such a way that Sparkle's "Window" and "Quick-
  679.          Print" options will be used to display your menu.
  680.  
  681.          .Com screens display instantly.  So they're often the best
  682.          way to display menus.  But .Com screens are separate files.
  683.          If you're concerned that this file might be separated from
  684.          your batch file, you might want to <D>raw your menu -- the
  685.          safest (but slowest) option.
  686.  
  687.        * MM is v-e-r-y easy to use.  So experiment with both approaches
  688.          to see which you prefer, which suits your needs the best.
  689.  
  690.  
  691.       The 2nd question actually looks like this:
  692.  
  693.          Enter a 2 - 8 character file name [default = MENU].  DON'T
  694.          add an extension (e.g.,'.Bat').  We'll add ".BAT" for you.
  695.  
  696.        * Just type in a 2 - 8 character file name, then press <Enter>.
  697.  
  698.        * If you leave the name blank, MM will create "MENU.BAT."
  699.  
  700.        * Please DO NOT enter extensions.  We'll add ".Bat" to
  701.          your batch file name.  And if you asked to save a ".COM"
  702.          file menu screen, we'll create an "executable screen"
  703.          with a name **similar** to your batch file -- but with
  704.          a ".COM" extension.  More on this "similarity" shortly
  705.  
  706.       Warning
  707.       =======
  708.  
  709.       If you enter a file name that already exists, MM will OVERWRITE
  710.       it -- without warning!  So, if you're not sure if a .Bat or .Com
  711.       file already exists, enter a very unusual name (like 999_xxx).
  712.       Then, after MM saves your files, just rename the .Bat and .Com
  713.       files to anything you like.  And be sure to edit your batch file
  714.       to update the name of .Com screen you're displaying.           
  715.  
  716.  
  717.       Executable .COM Menu Screens                                  MM.5
  718.       ============================
  719.  
  720.       If you tell MM to save "executable" .COM screens, it saves them
  721.       with the "file name" you entered -- but with the first letter
  722.       changed to "!".  For example:
  723.  
  724.        * If you save MENU.BAT, MM saves your COM screen as !ENU.COM.
  725.  
  726.        * If you save LOGON.BAT, MM saves the COM screen as !OGON.COM.
  727.  
  728.  
  729.       The reason for the unusual (ugly?) names for .Com files is that we
  730.       CANNOT save both a .Bat and a .Com file with the same name.  Why?
  731.  
  732.        * Suppose we saved both Menu.Com and Menu.Bat.  Later, when
  733.          you type "menu <Enter>" to run Menu.Bat it would NEVER run!
  734.          Menu.Com would run instead!
  735.  
  736.        * That's because when you run a program, DOS first looks for a
  737.          .Com file by that name.  If found, DOS runs it.  If DOS can't
  738.          find it, it looks for an .Exe file by that name.  If found,
  739.          DOS runs it.  If not found, DOS then looks for a .Bat file.
  740.  
  741.          Since ".BAT" files are LAST in this "pecking order," if
  742.          you have a batch file with the SAME NAME as a .Com or .Exe
  743.          file, your batch file may never run!
  744.  
  745.  
  746.       Feel free to rename the file(s) MM saves to anything you like.
  747.       But if you change the name of .Com screens, be sure to edit
  748.       your batch file to reflect the new file name.
  749.  
  750.                                                                        
  751.  
  752.  
  753.       CHOOSING COLORS                                               MM.6
  754.       ===============
  755.  
  756.       Finally, once you tell MM HOW to save your menu screen, it will
  757.       display your menu screen and give you a chance to choose colors.
  758.  
  759.  
  760.       By default, MM creates menus with:
  761.  
  762.        * a blue shadowed window
  763.  
  764.        * a single-line border around the window
  765.  
  766.        * a green backdrop (to highlight the blue window)
  767.  
  768.  
  769.       You may change one of these, all of them, or any combination.  To
  770.       do so, just press the cursor pad keys (you'll see instructions at
  771.       the bottom of your screen).  As you press the cursor pad keys,
  772.       you'll see your menu change.
  773.  
  774.        * Press ARROW keys to change the colors of the menu window itself.
  775.  
  776.          - Press Up/Down to select from 15 different foreground colors.
  777.  
  778.          - Press Left/Right to select from 8 background colors.
  779.  
  780.  
  781.        * Press HOME or END to change the border style.  There are
  782.          5 alternatives.  Try them all to see which you prefer.
  783.  
  784.  
  785.        * Press PGUP or PGDN to change the color of the backdrop.
  786.  
  787.          One of the options is black.  If you choose this, you'll
  788.          see no backdrop AND no shadow under the menu window --
  789.          since black shadows are invisible on black backgrounds.
  790.  
  791.  
  792.       NOTE:  The menu options themselves are printed in white on black.
  793.  
  794.        * We opted for simple colors here so your menu options would
  795.          be "readable" on ANY monitor -- color or monochrome.
  796.  
  797.        * If you prefer different colors, select the <D>raw option (not
  798.          the .Com screen option).  Then edit the batch file and change
  799.          the colors Sparkle uses to display text.
  800.  
  801.  
  802.       Press <Escape> when you like what you see.  MM will then save
  803.       both your screen and your batch file to disk. 
  804.  
  805.                                                                        
  806.  
  807.  
  808.       Vertical (not Horizontal) Menus.  Why?                        MM.7
  809.       ======================================
  810.  
  811.       MM creates VERTICAL scrolling bar menus.  But Sparkle can handle
  812.       either vertical -OR- horizontal scrolling bar menus.  Why can't
  813.       Menu Magic create horizontal menus?  For two reasons.
  814.  
  815.        * First, we offer another program (P-Screen) with which you
  816.          can create almost any text-mode screen you like.  You can
  817.          save these screens to "compressed" .Com screens (or to
  818.          "screen libraries" or ASCII files, etc.).  P-Screen's
  819.          ".Com" screens are about 1/2 the size of those MM creates --
  820.          thanks to P-Screen's screen compression.
  821.  
  822.          And P-Screen makes it very easy to add colors, draw lines
  823.          and boxes, add shading, move things around, copy or erase
  824.          things, add Big! Font messages (in over 20 Big! Font styles
  825.          for bold, attention-getting titles), etc.
  826.  
  827.          You'll see several of P-Screen's screens when you run Demo.Bat
  828.          -- which also demonstrates Sparkle's other menu options.
  829.  
  830.  
  831.        * Second, we wanted to keep Menu Magic small, fast and to-the-
  832.          point.  Since vertical bar menus are the most popular and
  833.          flexible type of scrolling bar menus, and since we didn't want
  834.          to duplicate capabilities that already exist in P-Screen, we
  835.          built MM to offer the most widely used option.
  836.  
  837.  
  838.       Menu screens DON'T mention <Escape>!
  839.       ====================================
  840.  
  841.       Menu screens that MM creates do NOT mention that you can press
  842.       <Escape> to exit menus altogether -- but that option DOES exist!
  843.  
  844.        * Once Sparkle turns your screen into a bar menu and takes over,
  845.          users must select an option -OR- press <Escape> to exit.
  846.  
  847.        * But what should we do if users press <Esc>?  We can't know
  848.          what YOU'D want to do, so we don't mention it.
  849.  
  850.        * Some people create menus with explicit options to "Quit."
  851.          Others prefer to use <Escape> as the Quit key.  If you want
  852.          users to know they can press <Escape> to do something, display
  853.          a message (using "Echo" or Sparkle's "Quick Print" option) to
  854.          tell users to press <Escape> to quit.
  855.  
  856.                                                                        
  857.  
  858.  
  859.       More Options (More than 8 Menu Options)                       MM.8
  860.       =======================================
  861.  
  862.       MM lets you enter up to 8 menu options.  This lets us display
  863.       options attractively, without crowding.  But if you need more
  864.       than 8 options, you have several choices.
  865.  
  866.       First, note that Sparkle can handle up to 25 menu options on
  867.       VERTICAL scrolling bar menu.  And Sparkle can also create
  868.       horizontal scrolling bar menus.  Finally, if you use Sparkle's
  869.       "ASK" option, you can to turn ANY screen (text -OR- graphics) into
  870.       a menu -- with as many options as you like.  Just display a screen
  871.       telling users to press a key to make a choice.  Then run Sparkle
  872.       and tell it which keys the user is allowed to press.  When users
  873.       press one of these keys, Sparkle will exit, telling you which key
  874.       they pressed (Sparkle sets the DOS errorlevel to let you know).
  875.  
  876.       In other words, Sparkle can turn ANY screen into a menu.  You don't
  877.       necessarily need MM to create the screen for you.  But if you use
  878.       Menu Magic, and you need more than 8 menu options, you can:
  879.  
  880.        1.  Include, on your menu, the option to go to another menu,
  881.            which can display up to 8 more choices.  There's no limit
  882.            to the number of menus you can have.  And each menu can
  883.            branch to other menus -- one option going forward, and
  884.            another option branching back go to an earlier menu.  To
  885.            elect this format, use MM to create 2 or more batch files.
  886.            Then merge them together into one batch file.
  887.  
  888.        2.  Create your menu screen in other ways.
  889.  
  890.            * Use the batch ECHO command to display your menu.
  891.  
  892.            * Use Sparkle's Window and Quick Print options to display
  893.              your menu -- with windows, shadows and colors if you like.
  894.  
  895.            * Or use our P-Screen program to create any text-mode screen 
  896.              you like.  P-Screen lets you save screens to screen libraries 
  897.              or ASCII files, which you can later edit.
  898.  
  899.                                                                        
  900.  
  901.  
  902.       ==================================================================
  903.                         Using SUPER SPARKLE (SS.Exe)                SS.1
  904.       ==================================================================
  905.  
  906.       Sparkle is fun!  So please experiment with its many options, sounds,
  907.       colors, etc.  For a list of options, type: SS <Enter>
  908.  
  909.       Sparkle will display this (PRINT this as a quick reference guide):
  910.  
  911.          Sounds  SS  1 # #2  (# = 1 to 35, 88 or 99; #2 = # of times)
  912.        Bar Menu  SS  2 TopRow LeftCol BotRow RightCol Color Direction
  913.             Ask  SS  3 Row Column Color /ValidKeys /Text
  914.       Big! Font  SS  4 Row Column Color CharacterCode /Text
  915.       QuikPrint  SS  5 Row Column Color /Text
  916.          Window  SS  6 TopRow LeftCol BotRow RightCol Color Frame /Text
  917.           Pause  SS  7 HowLong (optional:  99 = allow interrupt)
  918.         Monitor  SS  8 (optional: 99; Errorlevel = 1 if mono monitor)
  919.           Paint  SS  9 TopRow LeftCol BotRow RtCol Color  # (1=All, 0=Border)
  920.         Reverse  SS 10 TopRow LeftCol BotRow RtCol #Times # (1=All, 0=Border)
  921.       Bright BG  SS 11 # (1=Bright Backgrounds On, 0=Off)
  922.       Get Resp.  SS 12 Row Column Color Length # (1=Env./0=File) /Text /Name
  923.        DOS Ver.  SS 13 (Errorlevel will be 21, 30, 40, 62, etc.)
  924.       View File  SS 14 TopRow LeftCol BotRow RhtCol Color /File Name
  925.          Prompt  SS 15 Row Column Color # (# = 1, 2 or 3)
  926.       Dark Blue  SS 16 # (1=Dark Blue background on VGAs, 0=normal colors)
  927.       BIGScroll  SS 17 Color Char.Code Font# (1=B'Way, 2=Normal) #Times /Text
  928.       Fade_outs  SS 18 # (option 1 - 9) Color Slowdown (1 - 20)
  929.      B'Way Font  SS 19 # (1=B'way, 0=Normal) VGA Appears w/ LOW intensity text
  930.  
  931.       Choosing Options
  932.       ================
  933.  
  934.       Note that each option has a NUMBER.  To select options, just run
  935.       Sparkle and type in a number.  For example:  SS 1  (sound effects).
  936.       Each option also has sub-options (or instructions) you send Sparkle.
  937.       In general, run Sparkle like this:
  938.  
  939.                      SS  Option_#  1  2  3  4 ..... <enter>
  940.  
  941.            Where:   Option_# is a number from (1=Sound, 2=Menu, etc.)
  942.  
  943.                     1, 2, 3 ... etc. are sub-options (or instructions)
  944.  
  945.           Notice:   * A space MUST separate each item on the command line.
  946.  
  947.                     * If we ask for numbers, send only numbers (not A - Z).
  948.  
  949.                     * When you send us text, begin it with "/" (we'll
  950.                       explain shortly how to begin text with other than
  951.                       "/" -- in case you must use "/" in your text).
  952.  
  953.            Color:   Several options require a Color -- a # from 1 - 255
  954.                     telling us which foreground AND background color to use.
  955.                     See "Choosing Color Numbers" for tips on choosing colors.
  956.  
  957.       Errorlevel:   Some options return a DOS Errorlevel.  See "Testing
  958.                     Errorlevels" and the description of each option.   
  959.  
  960.  
  961.       Examples:                                                     SS.2
  962.       =========
  963.  
  964.       SOUNDS        SS 1 14
  965.  
  966.                     1 = Sound Effects.  14 = the 14th sound effect.
  967.  
  968.  
  969.       BIG! FONT     SS 4 1 1 112 219 /Big! Font
  970.  
  971.                     4 = print Big! Font messages.  Other items tell us:
  972.  
  973.                     - WHERE to print it (row 1, column 1 in this example).
  974.  
  975.                     - The COLORS to use (112 in this example:  black
  976.                       letters on a white background).
  977.  
  978.                     - Which character to CONSTRUCT your message with
  979.                       (ASCII 219 in this example; use ANY number 1 - 254).
  980.  
  981.                     - And WHAT to print ("Big! Font" in this example).
  982.  
  983.  
  984.       ASK           SS 3 25 35 15 /123 /Press 1, 2 or 3
  985.  
  986.                     3 = Ask (print a message or prompt and wait for a
  987.                     key).  Other instructions tell us where to print it,
  988.                     what color to use, and what message to print.
  989.  
  990.  
  991.       PROMPT        SS 15 25 23 78 3
  992.  
  993.                     15 = Prompt (print a dynamic prompt or message to
  994.                     tell users it's time to press a key).
  995.  
  996.                     - "25 23" tells Sparkle to print the prompt on line
  997.                       25, column 23.
  998.  
  999.                     - "78" tells us to use color 78 -- bright yellow on
  1000.                       a red background.
  1001.  
  1002.                     - And "3" selects the 3rd prompt option:  a scrolling
  1003.                       "Press any key to continue . . .".
  1004.  
  1005.       An IMPORTANT Note about sending TEXT
  1006.       ====================================
  1007.  
  1008.       For many Sparkle options, you'll specify "text" you want displayed.
  1009.       TO PAD BOTH ends of that text with <spaces>, begin AND end that
  1010.       text with "/" (or the "text marker" you've chosen; more on this
  1011.       later).  For example, to SCROLL a tall message across the screen
  1012.       AND have it clear itself, send Sparkle instructions like this:
  1013.  
  1014.          SS 17 4 219 0 0 /Scroll this message          /
  1015.                                              ^^^^^^^^^^^
  1016.       The extra spaces followed by "/" causes the message to clear
  1017.       itself from the screen.                                          
  1018.  
  1019.  
  1020.                 Debugging Batch Files; Sparkle's Error Codes        SS.3
  1021.       ==================================================================
  1022.  
  1023.       Sometimes batch files (like any "program") do things we didn't
  1024.       anticipate.  And we sometimes make mistakes when developing them.
  1025.       But figuring out what went wrong can often be difficult -- since
  1026.       batch files don't give us obvious feedback about our mistakes.
  1027.  
  1028.       Fortunately, Sparkle lets you turn "test mode" (SPT) ON.  This
  1029.       tells Sparkle to DISPLAY the results of various options.  To do
  1030.       this, at the DOS prompt type (note: "SPT" means Sparkle Test):
  1031.  
  1032.                 SET SPT=?<enter>  (NO spaces except after "SET")
  1033.  
  1034.       where "?" is:
  1035.  
  1036.         - Any character -- which will cause Sparkle to display the
  1037.           ErrorLevel at row 25, column 77, then move on.
  1038.  
  1039.         - PAUSE (the word PAUSE) -- which causes Sparkle to print the
  1040.           ErrorLevel, then wait for you to press a key before moving on.
  1041.  
  1042.       To turn this option OFF, type:  SET SPT=<enter>  (nothing after "=").
  1043.  
  1044.  
  1045.       How does this help?
  1046.       ===================
  1047.  
  1048.       Suppose you run Sparkle and nothing happens.  Why?  If you don't
  1049.       SET SPT=, you may never know.  But if you SET SPT=, Sparkle might
  1050.       suggest that you did something wrong by displaying one of these
  1051.       error codes (and by setting the DOS errorlevel to these numbers):
  1052.  
  1053.         255 - Option number out of range:  you specified no option,
  1054.               or the option number you specified was GREATER than
  1055.               the highest option Sparkle offers.
  1056.  
  1057.         254 - Illegal screen coordinates (e.g., a Row or Column of 195)
  1058.  
  1059.         253 - No menu options found (scrolling bar menus); or,
  1060.               File not found (View File); or,
  1061.               No text sent (for options that print text, Big! Fonts, etc.)
  1062.  
  1063.       Or, suppose you use Sparkle's dynamic PROMPT option and want to
  1064.       BRANCH depending on which key a user presses.  You add "If error-
  1065.       level ..." statements to your batch file -- but they're not
  1066.       working.  If you turn SPT ON, Sparkle will display the ASCII
  1067.       values of keys pressed.  You might discover, for example, that
  1068.       you asked users to press <Space>, but didn't count on someone
  1069.       pressing <Enter>.  Or you might have expected UPPER case letters,
  1070.       and didn't anticipate lower case letters.
  1071.  
  1072.  
  1073.       NOTE:  SET SPT= requires "environment space."  See "Running out of
  1074.       Environment Space" later in this manual.
  1075.                                                                        
  1076.  
  1077.  
  1078.             Changing the "Text Marker" -- SET SPM=?    (edit "?")   SS.4
  1079.       ==================================================================
  1080.  
  1081.       Several of Sparkle's options ask for text (e.g., Window), or a mes-
  1082.       sage (Big! Font) or a prompt or list of "valid keys" (Ask), etc.
  1083.  
  1084.       By default, Sparkle expects you to begin text with "/" --  Sparkle's
  1085.       "text marker."  But sometimes you must include "/" as part of your
  1086.       text or message.  If so, you can CHANGE the text marker.  To do so,
  1087.       at the DOS prompt (or in batch files), enter:
  1088.  
  1089.       SET SPM=?  ("SPM" means Sparkle Marker; NO spaces except after "SET")
  1090.  
  1091.       where "?" is ANY ASCII character you want to use to begin text.
  1092.  
  1093.       For example:   SET SPM=~   \   These tell Sparkle you'll use "~", or
  1094.                      SET SPM=[    )  "[" or "@" to mark the beginning of
  1095.                      SET SPM=@   /   text.  You can then use "/" AS text!
  1096.  
  1097.       To turn this feature OFF (to restore "/" as the text marker), type:
  1098.                SET SPM=<enter>   (notice there's nothing after "=").
  1099.  
  1100.       NOTE:   See "Running out of Environment Space" below.
  1101.  
  1102.       ALSO NOTE:  If you run a batch file and Sparkle prints NO TEXT,
  1103.       the likely cause is that SET SPM= and your batch file are out-of-
  1104.       synch:  your batch file is using one text marker, but you've used
  1105.       SET SPM= and told Sparkle to look for a different marker.
  1106.  
  1107.  
  1108.                          Running out of Environment Space
  1109.       ==================================================================
  1110.  
  1111.       DOS sets aside a small amount of RAM memory ("environment space")
  1112.       to store "environment variables" (in DOS 6.2, the default amount
  1113.       of environment space is 256 bytes).
  1114.  
  1115.       DOS stores several things in this "environment" -- your PATH
  1116.       statement, your PROMPT $... choices, COMSPEC=...., etc.  To
  1117.       see what's already in your environment, type:  SET <enter>.
  1118.  
  1119.       256 bytes isn't much.  And if your environment is already full,
  1120.       you may not be able to use SET SPT= or SET SPM=.
  1121.  
  1122.       Similarly, Sparkle's "Get Input" option lets you ask users to enter
  1123.       a 1 - 80 character response (like their name).  Sparkle can then save
  1124.       their response, either to a file, or in the "environment variable"
  1125.       you specify.  But, if a user's environment space is full, Sparkle
  1126.       will fail -- it won't be able to SET the variable you specify to
  1127.       what users enter (it WILL set the ErrorLevel to 100+, however).
  1128.  
  1129.       You (or your users) can INCREASE environment space by editing your
  1130.       CONFIG.SYS file and add/editing a line that looks this:
  1131.  
  1132.                      shell=C:\DOS\COMMAND.COM  /e:512
  1133.  
  1134.       "/e:512" reserves 512 bytes of RAM for environment variables.    
  1135.  
  1136.  
  1137.                             Option 1:   SOUND EFFECTS               SS.5
  1138.       ==================================================================
  1139.  
  1140.       To use:   SS  1  #  #2  (# = 1 to 35, 88 or 99) (#2 = # of times)
  1141.  
  1142.       Purpose:  To give you over 35 simple-to-complex sound effects.  You
  1143.                 may also repeat sound effects "#2" times (-or- until
  1144.                 users press a key).   This is optional; you can omit #2.
  1145.  
  1146.                  * Sound #88 = a ringing phone
  1147.  
  1148.                  * Sound #99 = part of the William Tell Overture
  1149.  
  1150.       Examples:
  1151.  
  1152.               SS 1  99
  1153.                  ^  ^
  1154.                  |  }"99" means play part of the William Tell Overture
  1155.                  |
  1156.                  }option 1 (Sound Effects)
  1157.  
  1158.           Replace "99" with 88 or any number from 1 to 35.  Numbers 6
  1159.           through 14 offer compound sounds -- trills, "Oh Oh," etc.
  1160.           Other numbers are simple tones of various durations.
  1161.  
  1162.               SS 1  6  25
  1163.                  ^  ^  ^
  1164.                  |  |  }repeat the sound 25 times, OR until a key is pressed
  1165.                  |  |
  1166.                  |  }sound effect #6
  1167.                  |
  1168.                  }option 1 (Sound Effects)
  1169.  
  1170.           If you include "#2" ("repeat sounds"), Sparkle plays the sound,
  1171.           then repeats it # times (for a total of 26 in this example).
  1172.           This is useful, for example, when you want to begin a LONG
  1173.           process (like de-fragmenting your hard disk), ignore your PC
  1174.           as it happens, then have Sparkle alert you when it's done.
  1175.  
  1176.           You can repeat sounds up to 9,999 times!  This effectively
  1177.           means that sound effects will continue until you press a key.
  1178.           Depending on which sound you choose, 9,999 times could mean
  1179.           a few minutes, a few hours or a few days!
  1180.  
  1181.             * Remember, you can press a key to stop!
  1182.             * But you'd better tell users that.
  1183.  
  1184.           You can press a key at any time to stop sounds played multiple
  1185.           times.  Between each sound effect, Sparkle pauses just a bit
  1186.           to ensure the sounds don't blend into one.  Sounds 88 and 99
  1187.           may NOT be repeated -- they're simply too long.
  1188.  
  1189.       NOTE:  Sparkle checks to see what type of CPU is being used.  It
  1190.              does this to ensure sounds are comparable regardless of
  1191.              whether an 8088, 286, 386, 486, Pentium, etc. is used.  In
  1192.              other words, the sounds should be similar regardless of how
  1193.              fast the PC is.  But speakers will affect sounds.         
  1194.  
  1195.  
  1196.                         Option 2:  SCROLLING BAR MENUS              SS.6
  1197.       ==================================================================
  1198.  
  1199.       To use:   SS 2 TopRow LeftCol BotRow RightCol Color Direction
  1200.  
  1201.       Purpose:  To turn ANY text-mode (not graphics-mode) screen into
  1202.                 a Vertical -or- Horizontal scrolling bar menu -- WITH
  1203.                 mouse support!  Here's what you do:
  1204.  
  1205.       1. Display a screen.  You can use Sparkle's Window and Quick Print
  1206.          options to create a menu.  You can "echo" text in a batch file.
  1207.          Or you can run "executable .Com screens" and blast screens up.
  1208.  
  1209.       2. Then run Sparkle like this:
  1210.  
  1211.              SS 2 TopRow LeftColumn BotRow RightColumn Color Direction
  1212.  
  1213.          Where:
  1214.  
  1215.              - "2" = Option 2 (Scrolling Bar Menus)
  1216.  
  1217.              - TopRow, LeftColumn, BotRow, RightColumn indicate WHERE
  1218.                the menu options are on your screen (screen "coordinates").
  1219.  
  1220.              - Color is a number from 1 - 127 (usually) indicating the
  1221.                color we should use to HIGHLIGHT menu options.  If zero,
  1222.                we'll use 112 (black on white).  See "Choosing Color
  1223.                Numbers" for help on determining this color number.
  1224.  
  1225.              - Direction = 1 (vertical menu) or 2 (horizontal menu)
  1226.  
  1227.              NOTE:  To determine TopRow, LeftColumn, BotRow and RightColumn:
  1228.  
  1229.                     1) Run "Ruler.Exe" -- our RAM-resident ruler.  When
  1230.                        your menu screen is visible, call up Ruler.  Move
  1231.                        the cursor to the top left corner of your menu.
  1232.                        Write down the Row/Column, then move to the bottom,
  1233.                        right corner.  Note its Row/Column, then uses
  1234.                        these numbers in your Sparkle command.
  1235.  
  1236.                     2) Or you can manually count rows and columns.
  1237.  
  1238.       3. Test Errorlevel.   (See "A Note About Testing Errorlevels")
  1239.  
  1240.          Sparkle returns a DOS Errorlevel indicating which option was
  1241.          selected.  Interpret the Errorlevel like this:
  1242.  
  1243.          1 to x    = The number of the option chosen (1 = the 1st option,
  1244.                      2 = 2nd option ... x = last option)
  1245.  
  1246.          27        = Esc was pressed
  1247.  
  1248.          254 or 255= Either your screen location variables were "wrong"
  1249.                      (e.g., Top Row <<greater than>> Bottom Row).
  1250.  
  1251.                      Or we found no TEXT / Menu Choices in the area
  1252.                      of the screen where you said your menu would be.  
  1253.  
  1254.  
  1255.      Scrolling Bar Menus (continued)                                SS.7
  1256.      ===================================================================
  1257.  
  1258.               SS 2  5 45  20 78 79 1
  1259.                  ^  ^ /   ^ /   |  ^
  1260.                  |  |/    |/    |  }It's a Vertical menu (choices up/down)
  1261.                  |  |     |     |
  1262.                  |  |     |     }Highlight menu options in White on Red
  1263.                  |  |     |
  1264.                  |  |     }menu ends on row 20, column 78
  1265.                  |  |
  1266.                  |  }menu starts on row 5, column 45
  1267.                  |
  1268.                  }option 2 (Scrolling Bar Menus)
  1269.  
  1270.       IMPORTANT NOTES on Creating Bar Menus: : : :
  1271.       ============================================
  1272.  
  1273.        1.  Once you define your menu's " screen coordinates," we scan
  1274.            the screen looking for "menu text."  We ignore blank lines
  1275.            and lines with only "graphics" (lines, boxes or shading).
  1276.  
  1277.            - ANY text found inside your screen coordinates WILL be
  1278.              considered menu text -- UNLESS you begin that line of text
  1279.              with ASCII character 255.  Character 255 tells Sparkle to
  1280.              ignore lines of text (which might explain what users should
  1281.              do, that you use to introduce something, etc.).
  1282.  
  1283.              You can enter character 255 in two ways:
  1284.  
  1285.              a) Create menu screens using our P-Screen program.  Move
  1286.                 the cursor to the beginning of each line of text you
  1287.                 want us to ignore.  Press Alt-A to display the "ASCII"
  1288.                 chart.  Move the cursor to the last character in the
  1289.                 chart (it will look blank).  Press <Enter> to accept it.
  1290.  
  1291.              b) Most word processors or editors let you enter "High
  1292.                 ASCII" characters.  Load your menu screen into your word
  1293.                 processor.  Move the cursor to the beginning of any line
  1294.                 of text you want us to ignore.  Hold down the Alt key,
  1295.                 then type "255" on the NUMERIC KEYPAD of your keyboard
  1296.                 (DON'T use the numbers at the top of your keyboard.
  1297.  
  1298.              Character 255 looks blank space on your screen.  You can
  1299.              "paint" it any color you want, or move, copy or delete it.
  1300.  
  1301.        2.  In Horizontal menus, use character 255 to "link" 2 or more
  1302.            words that are part of the same menu option.  For example:
  1303.  
  1304.                   Lotus 123    Paradox    WordPerfect   Quit
  1305.  
  1306.            This menu has 4 options.  But notice the space between
  1307.            "Lotus" and "123".  If we don't plug that space with char-
  1308.            acter 255 (or ANY non-space character), Sparkle WILL treat
  1309.            "123" as a menu option -- giving us 5 not 4 options.
  1310.                                                                              
  1311.  
  1312.  
  1313.       Important Notes on Scrolling Bar Menus (continued)            SS.8
  1314.       ==================================================================
  1315.  
  1316.        3.  In VERTICAL menus, each line should be a single menu choice.
  1317.  
  1318.             * Each line can include as many words as you like (and you
  1319.               needn't fill blanks between words with character 255).
  1320.  
  1321.             * If a menu option needs 2 or more lines, start the 2nd,
  1322.               3rd, etc. lines with character 255 -- so we ignore them.
  1323.  
  1324.  
  1325.        4.  In HORIZONTAL menus, ALL menu options must be on ONE line.
  1326.            And the first line of text we find that does NOT begin with
  1327.            character 255 will be treated as your menu line.  NOTE:
  1328.            TopRow and BotRow are usually the SAME for horizontal menus!
  1329.  
  1330.  
  1331.        5.  Sparkle HIGHLIGHTS menu choices using the color you specify.
  1332.  
  1333.            To ensure the highlight is visible, BE SURE to use a color
  1334.            that contrasts with the basic colors of your menu.  If you
  1335.            don't, the menu highlight will be hard or impossible to see.
  1336.            For example, if your menu is blue or red (i.e., dark), try 112
  1337.            (black on white).  But if your menu is light (cyan, white,
  1338.            yellow, etc.), consider a red (79) or blue (31) highlight.
  1339.  
  1340.            See "Choosing Color Numbers" for a chart that can help you
  1341.            choose a "color number."
  1342.  
  1343.            NOTE:  In earlier versions of Sparkle we highlighted menu
  1344.            option by REVERSING colors.  This simplified your task since
  1345.            you didn't have to tell us what color to use.  BUT, we got
  1346.            reports that *some* reversed colors were invisible on some
  1347.            monitors.  So we returned to the earlier approach (speci-
  1348.            fying a color) to give YOU greater safety and flexibility.
  1349.  
  1350.  
  1351.        6.  Using a MOUSE to select options in bar menus:
  1352.  
  1353.             * Click the LEFT button on any option to *highlight* it.
  1354.  
  1355.             * DOUBLE click the LEFT button on options to *select* them.
  1356.  
  1357.             * Sparkle uses only the left mouse button; it ignores others.
  1358.                                                                            
  1359.  
  1360.        7.  Using the KEYBOARD to select options in bar menus:
  1361.  
  1362.             * *Highlight* an option, then press <cr> to accept it.
  1363.  
  1364.             * To highlight options, press the Up or Down cursor keys,
  1365.               -or- press the first letter of the option you want.  If
  1366.               2 or more options begin with the same first letter, keep
  1367.               pressing that letter until we highlight the option you want.
  1368.                                                                        
  1369.  
  1370.  
  1371.                                Option 3:  ASK                       SS.9
  1372.       ==================================================================
  1373.  
  1374.       To Use:   SS  3  Row Column Color /ValidKeys /Text
  1375.  
  1376.       Purpose:  ASK lets you turn ANY screen into a menu screen.  Or
  1377.                 use ASK to pause until users press a key.  You can:
  1378.  
  1379.                 1) display messages anywhere on the screen (text mode ONLY)
  1380.                 2) display them in any color you want
  1381.                 3) wait for users to press one of the keys you specified,
  1382.                    then report an Errorlevel indicating which key was
  1383.                    pressed.  (See "A Note About Testing Errorlevels")
  1384.  
  1385.        YOU specify which keys we should exit on (Sparkle also exits when
  1386.        Escape is pressed).  For example, suppose you display a menu and
  1387.        ask users to choose options by pressing 1, 2, 3, 4 or Q to Quit.
  1388.  
  1389.         - Just tell us the Valid Keys are 1234Q.
  1390.  
  1391.         - If "ValidKeys" is NULL (empty or nothing), we'll wait until
  1392.           ANY KEY is pressed, then exit with Errorlevel set to 0.
  1393.  
  1394.        Example:
  1395.  
  1396.                SS 3 25 35 112 /1234q /Please press 1, 2, 3, 4 or [Q]uit
  1397.                   ^  ^ /  ^   ^      ^
  1398.                   |  |/   |   |      }print the message beginning with "/"
  1399.                   |  |    |   |
  1400.                   |  |    |   }wait until user presses one of these keys
  1401.                   |  |    |
  1402.                   |  |    }print the "prompt" in color 112 (black on white)
  1403.                   |  |
  1404.                   |  }print on Row 25, Column 35
  1405.                   |
  1406.                   }option 3 (ASK)
  1407.  
  1408.       NOTES on Ask
  1409.       ============
  1410.  
  1411.        - If ValidKeys AND Text are both blank, Sparkle prints nothing
  1412.          and simply waits until users press ANY key.
  1413.  
  1414.        - Sparkle sets the DOS Errorlevel to indicate which key was pressed.
  1415.  
  1416.          -- 27 means Escape was pressed.
  1417.  
  1418.          -- Otherwise it's the Ascii code of the UPPER CASE key pressed.
  1419.             APPENDIX III lists the Ascii codes for many keyboard charac-
  1420.             ters.  Note that Sparkle returns UPPER case keypresses.  We
  1421.             don't distinguish a from A.  But your list of Valid Keys can
  1422.             be in upper or lower case (or both).
  1423.  
  1424.          -- See "Notes on Testing Errorlevels" for examples of how to
  1425.             deal with these.
  1426.  
  1427.        - IMPORTANT:  You MUST use the "text marker" (/=default) to begin
  1428.          BOTH your list of valid keys AND the text to be printed.       
  1429.  
  1430.  
  1431.         ▌▌▌▌▌▌   ▌▌▌▌  ▌▌▌▌▌   ▐▐     ╬╬╬╬╬╬╬                    ╪╪  SS.10
  1432.          ▌▌  ▌▌   ▌▌  ▌▌   ▌▌  ▐▐      ╬╬   ╬                    ╪╪
  1433.          ▌▌  ▌▌   ▌▌  ▌▌   ▌▌  ▐▐      ╬╬ ╬    ║║║║║   ││││││  ╪╪╪╪╪╪
  1434.          ▌▌▌▌▌    ▌▌  ▌▌       ▐▐      ╬╬╬╬   ║║   ║║  ││   ││   ╪╪
  1435.          ▌▌  ▌▌   ▌▌  ▌▌ ▌▌▌▌  ▐▐      ╬╬ ╬   ║║   ║║  ││   ││   ╪╪
  1436.          ▌▌  ▌▌   ▌▌  ▌▌   ▌▌          ╬╬     ║║   ║║  ││   ││   ╪╪
  1437.         ▌▌▌▌▌▌   ▌▌▌▌  ▌▌▌▌▌   ▐▐     ╬╬╬╬     ║║║║║   ││   ││   ╪╪╪╪
  1438.       ==================================================================
  1439.  
  1440.       To Use:   SS  4  Row Column Color CharacterCode /Text
  1441.                    -4  Row Column Color CharacterCode /Text
  1442.  
  1443.       Purpose:  Big! Font, prints messages 7 - 8 lines high.  Each
  1444.                 character will be 8 columns wide.  You can:
  1445.  
  1446.                 - display Big! Font messages anywhere on the screen
  1447.                 - display them in any color you want
  1448.                 - "build" messages using ANY ASCII character
  1449.  
  1450.          NOTE:  Using "-4" tells Sparkle to use ALTERNATING colors.
  1451.                 While foreground colors are fixed (run Demo.Bat to
  1452.                 see examples), you STILL send a Color # to tell Sparkle
  1453.                 which BACKGROUND color to use.
  1454.  
  1455.       Example:
  1456.  
  1457.                  SS 4  9  1 12  219 /Hi There !
  1458.                     ^  ^ /  ^   ^   ^
  1459.                     |  |/   |   |   }print the message beginning with "/"
  1460.                     |  |    |   |
  1461.                     |  |    |   }"Build" characters using ASCII character 219
  1462.                     |  |    |
  1463.                     |  |    }print in color 12 (Bright Red on Black)
  1464.                     |  |
  1465.                     |  }begin printing on Row 9, Column 1
  1466.                     |
  1467.                     }option 4 (Big! Font)
  1468.  
  1469.       NOTES on Big! Font
  1470.       ==================
  1471.        * Since each character is 8 columns wide, only 10 Big! Font
  1472.          characters fit on 80-column screens.
  1473.  
  1474.        * "Row" is the TOP row on which to begin printing.  Most Big!
  1475.          Font characters will have 7 lines.  But characters with
  1476.          descenders (g, y, q, p, etc.) also need the 8th line.
  1477.  
  1478.          - Be sure to specify a Row 7 - 8 lines above the bottom of your
  1479.            screen -- or you won't see the bottom of the characters.
  1480.  
  1481.          - Sparkle WILL print on 43- or 50-line screens.
  1482.  
  1483.        * Sparkle "builds" characters using the ASCII character you specify.
  1484.          If you specify "0" we'll build each character using THAT char-
  1485.          acter (ie., we'll build a "G" with Gs, an "X" with Xs, etc.).
  1486.          - Use 219 - 223 for bold, solid or "striped" characters.
  1487.          - Use 1 or 2 for "happy faces," 176 - 178 for shaded characters.
  1488.          - ANY ASCII character from 1 to 254 will work.                
  1489.  
  1490.  
  1491.                             Option 5:  QUICK PRINT                 SS.11
  1492.       ==================================================================
  1493.  
  1494.        To use:   SS  5  Row Column Color /Text
  1495.  
  1496.        Purpose:  Quickly print text ANYWHERE on your screen in ANY color.
  1497.                  You can print ANY Ascii character from 1 - 255 -- you're
  1498.                  not limited to printing normal keyboard characters.
  1499.  
  1500.        Example:
  1501.  
  1502.                  SS 5  25 25  112  /Good Morning
  1503.                     ^   ^ /   ^    ^
  1504.                     |   |/    |    }print the message beginning with "/"
  1505.                     |   |     |
  1506.                     |   |     }print in color 112 (black on white)
  1507.                     |   |
  1508.                     |   }begin printing on Row 25, Column 25
  1509.                     |
  1510.                     }option 5 (Quick Print)
  1511.  
  1512.                                                                        
  1513.  
  1514.  
  1515.                              Option 6:  WINDOWS                    SS.12
  1516.       ==================================================================
  1517.  
  1518.        To Use:   SS  6  TopRow LeftCol BotRow RightCol Color Frame /Text
  1519.                  SS -6  Draws an EXPLODING window (all else is the same).
  1520.                         Exploding windows GROW to the size you specify.
  1521.  
  1522.        Purpose:  Quickly display windows (boxes) on the screen in any color.
  1523.                  - Choose from over 250 frame styles!
  1524.                  - Windows can be shadowed (send NEGATIVE Frame #), or not.
  1525.                  - You can include a "title", centered on the top row.
  1526.                  - NEGATIVE color #s mean FILL areas with ASCII characters.
  1527.  
  1528.        Frame     Sparkle offers over 250 frame styles.  Select these by
  1529.        styles:   setting "Frame" to 1 to 255.  Frame #s 1 - 5 include:
  1530.  
  1531.                    1 = Single line all around                        (┌)
  1532.                    2 = Double line all around                        (╔)
  1533.                    3 = Double horizontal line, single vertical line  (╒)
  1534.                    4 = Single horizontal line, double vertical line  (╓)
  1535.                    5 = Bolder solid line                             (▐▀)
  1536.                    6 = Like 5, but 2 corners are "notched"
  1537.  
  1538.                  Frame numbers from 7 - 255 tell Sparkle to draw window
  1539.                  in that ASCII character.
  1540.  
  1541.       Filling    NEGATIVE color numbers tell Sparkle to FILL areas with the
  1542.       Windows    ASCII character you send as a Frame #.  For example, try:
  1543.  
  1544.                    7, 249 or 250 = dots of various sizes  (can't show here)
  1545.                     32 = The Space character -- a solid patch of color
  1546.                     etc.  You get the idea.  Experiment!
  1547.  
  1548.        Frameless ASCII characters 32 and 255 are blank.  Use these frame
  1549.        Windows:  "styles" to create frameless splashes of color!  Use
  1550.                  -32 or -255 to get shadowed splashes of color!
  1551.  
  1552.        Titles:   Sparkle centers "/Text" on the top row of the window.
  1553.  
  1554.        Shadow:   To request a "drop shadow" for windows, send Sparkle a
  1555.                  NEGATIVE frame number (e.g., -2).  Shadows are drawn
  1556.                  right of and below your window.  Be sure to allow for
  1557.                  TWO extra columns on the right, and ONE extra row on
  1558.                  the bottom of shadowed windows.
  1559.  
  1560.        Example:
  1561.  
  1562.                 SS -6  5 7  20 75  79  -1  /My Window
  1563.                     ^   ^ /  ^ /    ^   ^   ^
  1564.                     |   |/   |/     |   |   }Center this title on the top line
  1565.                     |   |    |      |   }Frame style 1 (negative = shadowed)
  1566.                     |   |    |      }Use color 79 (White on Red)
  1567.                     |   |    }Window ends on row 20, column 75 (shadow below)
  1568.                     |   }Window starts on row 5, column 7 (shadow on right)
  1569.                     }option -6 (Exploding Window)                      
  1570.  
  1571.  
  1572.                              Option 7:  PAUSE                      SS.13
  1573.       ==================================================================
  1574.  
  1575.        To Use:   SS  7  HowLong  99 (99 is optional; it means let users
  1576.                         press a key to interrupt the pause)
  1577.  
  1578.        Purpose:  To allow batch files to briefly pause, then continue.
  1579.  
  1580.                   - You may pause from 1/3 second to several minutes.
  1581.  
  1582.                   - By adding "99" you'll let users "interrupt" (bypass)
  1583.                     the pause, and move on.  This is optional.
  1584.  
  1585.        Examples:
  1586.  
  1587.                  SS 7  12
  1588.                     ^  ^
  1589.                     |  }Pause for 4 seconds (each # = 1/3 second)
  1590.                     |
  1591.                     }option 7 (Pause)
  1592.  
  1593.  
  1594.                  SS 7  15  99
  1595.                     ^  ^   ^
  1596.                     |  |   }Pause, but let user "press a key" to go on
  1597.                     |  |
  1598.                     |  }Pause for 5 seconds (each # = 1/3 second)
  1599.                     |
  1600.                     }option 7 (Pause)
  1601.  
  1602.       NOTES on Pause
  1603.       ==============
  1604.  
  1605.        * "HowLong" is measured in 1/3 second increments.  "12" tells
  1606.          Sparkle to pause 4 seconds (12/3 = 4).  Similarly, "24" means
  1607.          pause 8 seconds (24/3 = 8).
  1608.  
  1609.          An easy way to decide what number to use is to decide how
  1610.          many SECONDS you want to pause, then MULTIPLY that by 3.
  1611.  
  1612.        * To let users "press a key" to interrupt the pause and move on,
  1613.          send Sparkle 2 numbers:  HowLong -AND- 99.   For example:
  1614.  
  1615.             SS 7 6 99   (pause 2 seconds; but let users proceed)
  1616.  
  1617.        * Sparkle checks to see what type of CPU is being used -- to
  1618.          ensure pauses are the same regardless of whether an 8088, 286
  1619.          386, 486, Pentium, etc. is being used.
  1620.  
  1621.          HOWEVER, the speed of disk drives WILL affect pauses.  That's
  1622.          because Sparkle must load first, and then pause.  While Sparkle
  1623.          is small and loads quickly, floppy disks are 10 - 20 times
  1624.          SLOWER than hard disks.  If your batch files will run off of
  1625.          different types of disks, test them on different drive types to
  1626.          determine the length of a pause that's a "happy medium" on all
  1627.          drives.                                                    
  1628.  
  1629.  
  1630.                              Option 8:  MONITOR                    SS.14
  1631.       ==================================================================
  1632.  
  1633.        To Use:   SS  8  99 ("99", optional, is explained below)
  1634.  
  1635.  
  1636.        Purpose:  Report what type of display adapter AND monitor is
  1637.                  active.  This can help you select colors to use in batch
  1638.                  files -- those appropriate for color or mono monitors.
  1639.  
  1640.  
  1641.        Example:
  1642.  
  1643.                  SS 8
  1644.                     ^
  1645.                     }option 8 (Monitor type)
  1646.  
  1647.                  SS 8  99
  1648.                     ^  ^
  1649.                     |  }Set Errorlevel=1 if a monochrome monitor is detected
  1650.                     |   (regardless of the type of display adapter present)
  1651.                     |
  1652.                     }option 8 (Monitor type)
  1653.  
  1654.       NOTES on Monitor
  1655.       ================
  1656.  
  1657.        * Option 8 tells Sparkle to set the DOS Errorlevel based on BOTH
  1658.          the type of display adapter AND the type of monitor detected.
  1659.  
  1660.          If you run Sparkle with NO options (ie., Sparkle 8), it sets
  1661.          the Errorlevel as follows:
  1662.  
  1663.            1 = Monochrome adapter            2 = Hercules adapter
  1664.            3 = CGA adapter
  1665.            4 = EGA adapter/Mono monitor      5 = EGA adapter/Color monitor
  1666.            6 = VGA adapter/Mono monitor      7 = VGA adapter/Color monitor
  1667.            8 = MCGA adapter/Mono monitor     9 = MCGA adapter/Color monitor
  1668.           10 = EGA adapter/CGA monitor      11 = IBM 8514/A adapter
  1669.  
  1670.        * NOTE that options 1, 2, 4, 6 and 8 ALL indicate a monochrome
  1671.          monitor is being used.  If all you must know is if the monitor
  1672.          is Color or Monochrome, run Sparkle like this:   SS  8  99
  1673.  
  1674.           - "99" tells Sparkle to set Errorlevel = 1 when monochrome
  1675.             monitors are detected (ie., if Sparkle would normally report
  1676.             1, 4, 6 or 8).
  1677.  
  1678.           - This can simplify testing Errorlevels to something like:
  1679.  
  1680.             If Errorlevel 3 goto ItsColor   'If greater than or equal to 3..
  1681.             Goto ItsMonochrome              'Otherwise, assume it's mono.
  1682.  
  1683.        THE NEXT PAGE has examples of how you can use Option 8 to set
  1684.        options "on the fly" in batch files.                            
  1685.  
  1686.  
  1687.        Option 8 MONITOR  (continued)                               SS.15
  1688.  
  1689.  
  1690.        Two DOS features (SET and "named parameters") can help customize
  1691.        batch files (select appropriate colors) -- depending on the type
  1692.        of monitor Sparkle tells you is active.  (These features may NOT
  1693.        be available with early DOS versions -- 2.x or earlier.)
  1694.  
  1695.        "Named parameters" let you define "variables" you can use later
  1696.        in batch files.  Basically, you:
  1697.  
  1698.         * Use DOS' SET command to SET variable(s) to specific values
  1699.           (e.g., SET ErrSound=12, or SET MyColor=15, or SET HiLite=112).
  1700.  
  1701.         * Run Sparkle and use variable NAMES rather than values (e.g.,
  1702.           SS 1 %ErrSound% -- note "%" on BOTH sides of "ErrSound").
  1703.  
  1704.  
  1705.        Here's an example.  Notice how we will:
  1706.  
  1707.          1.  Run Sparkle to see if a color monitor is being used.
  1708.  
  1709.          2.  Depending on the type of monitor detected (color or mono),
  1710.              we SET a variable called "WhichClr" to a color appropriate
  1711.              for that monitor.
  1712.  
  1713.              "WhichClr" will now be available to every other line in
  1714.              our batch file -- as long as we use the variable name.
  1715.  
  1716.          3.  We then use the variable NAME to tell Sparkle which color
  1717.              to print with.
  1718.  
  1719.              -- NOTICE that when we use variables in batch files,
  1720.                 we place it between TWO percent signs (e.g.,
  1721.                 %WhichClr%).  This is REQUIRED by DOS!
  1722.  
  1723.                  SS 8 99                       '"99" since we only need to
  1724.                                                'know if it's color or mono
  1725.  
  1726.             If Errorlevel 3 goto _PrtInColor   'if 3 or higher, it's color
  1727.  
  1728.             Set WhichClr=112                   'If 1 or 2, it's a
  1729.                                                'monochrome monitor; use
  1730.                                                'simple Black on White.
  1731.  
  1732.             SS 5 21 15 %WhichClr% / MONOCHROME monitor detected
  1733.  
  1734.             goto Got_Monitor ("jump" over the Color section)
  1735.  
  1736.             :_PrtInColor
  1737.  
  1738.             Set WhichClr=78                     'It's color, SET "WhichClr"
  1739.                                                 'to 78  (Yellow on Red).
  1740.             SS 5 21 15 %WhichClr% / COLOR monitor detected
  1741.  
  1742.             :Got_Monitor  (continue. . .)                            
  1743.  
  1744.  
  1745.                             Option 9:   PAINT                      SS.16
  1746.       ==================================================================
  1747.  
  1748.           Note:   Paint and Reverse Color work in similar ways.  And
  1749.                   you can use paint and reverse in quick succession
  1750.                   to create some interesting displays.  See "Notes on
  1751.                   Paint and Reverse Color."
  1752.  
  1753.  
  1754.          Syntax:  SS  9  TopRow LeftCol BotRow RightCol Color_#  #
  1755.  
  1756.  
  1757.         Purpose:  Paint any area of text screens in any of 255 colors.
  1758.  
  1759.                   - Paint anything from 1 character to the full screen,
  1760.                     or any rectangular area in between.
  1761.  
  1762.                   - You can paint using blinking colors if you like.  And
  1763.                     you can paint the entire area, or just the border
  1764.                     around the area.
  1765.  
  1766.                   - If you "turn on" bright backgrounds (option #11), and
  1767.                     then paint with blinking colors, they'll be displayed
  1768.                     as stunning bright backgrounds (on most color monitors).
  1769.                     See Option 11, Bright Backgrounds for details.
  1770.  
  1771.  
  1772.       To Use it:  SS 9 TopRow LeftCol BotRow RightCol  Color_#  #
  1773.  
  1774.                   Where:
  1775.                     - "9" = Option #9 (the Paint Screen option)
  1776.  
  1777.                     - TopRow LeftCol BotRow RightCol  indicate the
  1778.                       rectangular area of the screen you want to paint.
  1779.  
  1780.                       The top left corner of your screen would be row 1,
  1781.                       column 1.  The bottom right corner of 25-line
  1782.                       screens would be 25, 80.
  1783.  
  1784.                     - Color_# is a number from 0 to 255 indicating both
  1785.                       the foreground and background color.  See "Choosing
  1786.                       Color Numbers" for details.
  1787.  
  1788.                     - "#" is 1 or 0.  If it's 1, Sparkle paints the
  1789.                       entire area you specified.  If it's 0, Sparkle
  1790.                       paints just the border around the area.
  1791.  
  1792.                                                                        
  1793.  
  1794.  
  1795.                          Option 10:   REVERSE COLOR                SS.17
  1796.       ==================================================================
  1797.  
  1798.           Note:   Paint and Reverse Color work in similar ways.  And
  1799.                   you can use paint and reverse in quick succession
  1800.                   to create some interesting displays.  See "Notes on
  1801.                   Paint and Reverse Color."
  1802.  
  1803.  
  1804.          Syntax:  SS  10  TopRow LeftCol BotRow RightCol  Times  #
  1805.  
  1806.  
  1807.         Purpose:  Reverse colors in any area of text screens.  By
  1808.                   "reverse" we mean that the foreground color becomes
  1809.                   the background, and the background becomes the
  1810.                   foreground.
  1811.  
  1812.                   - "Times" means "how many times."  If it's greater
  1813.                     than 1, we'll reverse the colors, pause about 1
  1814.                     second, then reverse them again, then again, then
  1815.                     .... as many times as you specify.  This is very
  1816.                     handy to draw attention to areas of the screen,
  1817.                     then move on.
  1818.  
  1819.                     If you reverse areas an EVEN number of times,
  1820.                     you'll end up with the original colors.
  1821.  
  1822.                   - You can reverse anything from 1 character to the
  1823.                     full screen, or any rectangular area in between.
  1824.  
  1825.                   - If the final parameter ("#") is "1," we'll reverse
  1826.                     the entire area.  If it's "0," we'll reverse just
  1827.                     the border around the area.
  1828.  
  1829.  
  1830.       To Use it:  SS 10 TopRow LeftCol BotRow RightCol  Times  #
  1831.  
  1832.                   Where:
  1833.                     - "10" = Option #10 (the Reverse Colors option)
  1834.  
  1835.                     - "TopRow LeftCol BotRow RightCol " indicate the
  1836.                       rectangular area of the screen you want reversed.
  1837.  
  1838.                       The top left corner of your screen would be row 1,
  1839.                       column 1.  The bottom right corner of 25-line
  1840.                       screens would be 25, 80.
  1841.  
  1842.                     - "Times" is a number from 1 to (anything) indicating
  1843.                       how many times we should reverse colors.  Remember,
  1844.                       every second time restores the original colors.
  1845.                       So use EVEN numbers to end up with original colors.
  1846.                       Use ODD numbers to end up with the colors reversed.
  1847.  
  1848.                     - "#" is 1 or 0.  If it's 1, Sparkle will reverse
  1849.                       the entire area you specified.  If it's 0, just
  1850.                       the border around the area will be reversed.    
  1851.  
  1852.  
  1853.                        Notes on Paint and Reverse Color            SS.18
  1854.       ==================================================================
  1855.  
  1856.        * Reverse Color literally reverses the foreground and background
  1857.          colors in areas you specify.  Please note that some color com-
  1858.          binations look fine in normal mode but NOT when reversed.  In
  1859.          fact, text may be unreadable if you reverse certain colors.
  1860.  
  1861.          - IF you want text to be readable whether it's in normal or
  1862.            reversed mode, begin with highly contrasting colors (eg.,
  1863.            White on Black or Blue), and AVOID bright foreground colors.
  1864.  
  1865.          - OR, make sure you reverse colors an EVEN number of times so
  1866.            that when we're done, your original colors are restored.
  1867.  
  1868.  
  1869.        * If you enter "illegal" screen coordinates (e.g., a top row
  1870.          greater than the bottom row), one of two things may occur:
  1871.          1) nothing; or, 2) a strangely painted screen.
  1872.  
  1873.          In other words, nothing tragic should occur.  For example, if
  1874.          your screen is in 25 row by 80 column mode, and you tell Sparkle
  1875.          to paint column 10 to column 5343, Sparkle will keep wrapping
  1876.          around the screen until it paints about 5300 characters.
  1877.  
  1878.  
  1879.        * Both Paint and Reverse work fine on 43 or 50 line screens.  Of
  1880.          course it's up to you to put your screen in these modes first.
  1881.  
  1882.  
  1883.        * To paint with Bright Background colors, first turn bright back-
  1884.          grounds on (see the next page), then paint something using
  1885.          blinking colors.  You get blinking colors by choosing a color
  1886.          from the color chart you'll find later, then adding 128 to the
  1887.          color number.
  1888.  
  1889.                                                                        
  1890.  
  1891.  
  1892.                         Option 11:   BRIGHT BACKGROUNDS            SS.19
  1893.       ==================================================================
  1894.  
  1895.          Syntax:  SS  11  #    ("#" is 1 = ON, 0 = OFF)
  1896.  
  1897.         Purpose:  To display things in colors you normally can't get.
  1898.                   To turn bright background colors on -or- off.
  1899.  
  1900.       IMPORTANT:  In text mode, PC monitors can normally display 128
  1901.                   colors (by combining 16 foreground with 8 background
  1902.                   colors).  You can also make these colors blink, giving
  1903.                   you 128 more colors.  BUT, on color monitors, you can
  1904.                   turn blinking colors into striking bright backgrounds.
  1905.  
  1906.                   Bright backgrounds are achieved by using BLINKING
  1907.                   FOREGROUND colors, and then telling the PC to display
  1908.                   blinking as bright backgrounds.  This means:
  1909.  
  1910.                   - You CAN'T mix blinking foregroundq and bright back-
  1911.                     grounds on the same screen:  they're exclusive.
  1912.  
  1913.                   - You CAN, however, mix bright and normal backgrounds.
  1914.  
  1915.                   Bright backgrounds can ONLY be displayed on color-
  1916.                   capable monitors.  If you print or paint with bright
  1917.                   backgrounds on Hercules or monochrome monitors (and
  1918.                   older IBM CGA monitors), you'll get BLINKING INSTEAD!
  1919.  
  1920.                   In short, you need a CGA, EGA or VGA monitor to success-
  1921.                   fully use this option.  On some older IBM CGA monitors,
  1922.                   you'll get blinking instead of bright backgrounds.  If
  1923.                   you're unsure what type of monitor will be in use when
  1924.                   your batch file runs, you may want to AVOID this option.
  1925.  
  1926.  
  1927.       To Use it:  SS 11 #
  1928.  
  1929.                     - "11" = Option #11 (the Bright Background option)
  1930.  
  1931.                     - "#" = 1 (turn ON) or 0 (turn OFF) bright backgrounds
  1932.  
  1933.       Once you turn bright backgrounds on:
  1934.  
  1935.        * Anything currently on your screens that's blinking will stop
  1936.          blinking and appear with bright backgrounds.
  1937.  
  1938.        * Anything you subsequently print or paint with blinking colors
  1939.          will be displayed with bright backgrounds instead.
  1940.  
  1941.          - To print using bright backgrounds, choose the color you want
  1942.            to print with from the Color Table below.  Then add 128 to it
  1943.            to turn it into a blinking color.
  1944.  
  1945.        * If you print or paint using bright backgrounds, then turn bright
  1946.          backgrounds off, at least part of your screen will start blinking.
  1947.  
  1948.                                                                        
  1949.  
  1950.  
  1951.                           Option 12:  GET INPUT                    SS.20
  1952.       ==================================================================
  1953.  
  1954.          Syntax:  SS  12  Row Column Color Length # /Prompt /Name
  1955.  
  1956.  
  1957.         Purpose:  This sophisticated option lets you get input from
  1958.                   users (from 1 to 80 characters), then save it to
  1959.                   either a file -or- an environment variable.  For
  1960.                   example, get passwords.  Or get users' names, and
  1961.                   then "customize" batch file messages by including
  1962.                   users' names using DOS' "named parameters" feature.
  1963.                   See the section called "Using DOS' Named Parameters"
  1964.                   for details.
  1965.  
  1966.                   - Setting environment variables may NOT work with DOS
  1967.                     versions 1.x or 2.x.  Therefore, before using this,
  1968.                     you might want to use Sparkle's "Get DOS Version"
  1969.                     option to see which version of DOS is being used.
  1970.  
  1971.                     There must ALSO be enough ENVIRONMENT SPACE (memory)
  1972.                     to save information in environment variables.  We'll
  1973.                     discuss this issue below.
  1974.  
  1975.                   - If you tell Sparkle to set an environment variable,
  1976.                     you can use DOS' "named parameters" feature to use
  1977.                     this variable later in your batch file.
  1978.  
  1979.                   - You can specify a prompt (eg., "Enter your ID #--> ").
  1980.  
  1981.                   - You can specify the MAXIMUM number of characters to
  1982.                     accept.  If "Length" is NEGATIVE, it tells Sparkle
  1983.                     the # is also the MINIMUM.  In this case, you MUST
  1984.                     enter, say, exactly 6 characters.  No more, no less.
  1985.  
  1986.                   - You can specify where on the screen we'll print the
  1987.                     prompt, and what colors to use.  Prompts are optional.
  1988.  
  1989.  
  1990.       IMPORTANT:  This is the only Sparkle option that might cause
  1991.                   errors.  As Sparkle exits this option, it sets the
  1992.                   DOS Errorlevel to let you know what happened.  See
  1993.                   "A Note On Testing Errorlevels."
  1994.  
  1995.                   If the Errorlevel is 0, no error occurred.  If it's
  1996.                   greater than 0, an error occurred, possibly due to:
  1997.  
  1998.                    - Disk or Drive errors when saving output to a file.
  1999.  
  2000.                    - Errors creating an environment variable (105 = too
  2001.                      little environment space, 103 = illegal variable name).
  2002.  
  2003.                    - You entered illegal screen coordinates (eg., you told
  2004.                      us to print the prompt or get input in column 90 on
  2005.                      an 80 column monitor).
  2006.                                                                        
  2007.  
  2008.  
  2009.                                                                     SS.21
  2010.  
  2011.       To Use it:  SS 12 Row Column Color Length # /Prompt /Name
  2012.  
  2013.                     - "12" = Option #12 (the Get Input option)
  2014.  
  2015.                     - "Row  Column" indicate where on the screen we should
  2016.                       print the prompt (if any), then pause to get input.
  2017.  
  2018.                     - Color is a number from 0 to 255 indicating both
  2019.                       the foreground and background color.  See "Choosing
  2020.                       Color Numbers" for details.  We use the same color
  2021.                       to print the prompt and while you're typing.
  2022.  
  2023.                     - Length is the maximum number of characters to
  2024.                       allow.  If Length is NEGATIVE, you're telling
  2025.                       Sparkle to accept EXACTLY the number of characters
  2026.                       you specify -- no more, no less.  Be careful here.
  2027.                       If you use NEGATIVE length numbers, BE SURE to
  2028.                       tell users to enter EXACTLY the # of characters
  2029.                       you insist on.
  2030.  
  2031.                     - "#" is 1 or 0.  "1" tells Sparkle2 to save what's
  2032.                       entered to an environment variable.  "0" means
  2033.                       save what's been entered to a file on disk.  In
  2034.                       either case the NAME used will be the name you
  2035.                       specify in the "/Name" variable.
  2036.  
  2037.                     - "/Prompt" is the prompt string you'd like us to
  2038.                       display at Row, Column.  This is optional.  If
  2039.                       /Prompt is blank, we'll pause at Row, Column to
  2040.                       get input.  You MUST include the "/" even if you
  2041.                       want no prompt.
  2042.  
  2043.                     - "/Name" is the name of a file -or- environment
  2044.                       variable we'll use to pass what's been entered
  2045.                       back to you.  If "/Name" is blank, we'll use "SS".
  2046.  
  2047.  
  2048.       NOTE:   If you tell Sparkle to save user input to a file (# = 0),
  2049.               we'll APPEND that input to the file.  This means that if
  2050.               you use this option several times, the file would end up
  2051.               with several lines in it -- one for each time you invoked
  2052.               this option.  IF you need one-line files, delete the file
  2053.               before running Sparkle.  For example:
  2054.  
  2055.               REM  ------ We're creating a file called SP_TEMP ------
  2056.               if not exist SP_TEMP goto Proceed
  2057.               del SP_TEMP
  2058.               :Proceed
  2059.               SS  12  1 10 79 -12 0 /Enter PASSWORD --> /SP_TEMP
  2060.                                                                        
  2061.  
  2062.  
  2063.                          Using DOS' Named Parameters               SS.22
  2064.       ==================================================================
  2065.  
  2066.       Sparkle's "Get Input" option lets you SET environment variables
  2067.       equal to what the user enters.  You can later use DOS' "named
  2068.       parameter" feature to access these variables.  Please note that:
  2069.  
  2070.        1. Early versions of DOS may not allow this.  You might consider
  2071.           using Sparkle's "Get DOS version" option before trying this.
  2072.  
  2073.        2. You MUST have free "environment space" to SET variables.
  2074.  
  2075.           - The amount of environment space needed is equal to the
  2076.             length of the variable NAME, PLUS the length of user input.
  2077.             For example, if you ask for "PASSWORD" (a NAME with 8
  2078.             characters), and the password can enter 10 characters, you
  2079.             will need about 20 bytes of environment space.
  2080.  
  2081.           - DOS typically doesn't tell you how much environment space
  2082.             is free.  But programs like QuarterDeck's Manifest can.
  2083.  
  2084.           - To INCREASE environment space, edit your CONFIG.SYS file.
  2085.             Add a line like (or edit the line that looks like) this:
  2086.  
  2087.                      shell=C:\DOS\COMMAND.COM  /e:512
  2088.  
  2089.            "/e:512" reserves 512 bytes of RAM for environment variables.
  2090.            Note that DOS already allocates some environment space to
  2091.            store things like your PATH statement, your PROMPT $..., etc.
  2092.            For example, by default, DOS 6.2 reserves 256 bytes.
  2093.  
  2094.       Using Named Parameters
  2095.       ======================
  2096.  
  2097.       To use the variables that Sparkle SETs, use DOS' "named parameter"
  2098.       feature.  "Named parameters" let you define "variables" you can
  2099.       use later in your batch files.  Basically, you:
  2100.  
  2101.        * SET variables to specific values (eg., SET PASSWORD=MyName).
  2102.          Sparkle's Get Input option can do this for you.
  2103.  
  2104.        * Later in your batch files, you refer to (or access) variables
  2105.          by surrounding variable NAMES with "%" as in "%PASSWORD%"
  2106.          DOS replaces "%PASSWORD%" with that variable's "value."
  2107.  
  2108.       For example, suppose you use Sparkle's Get Input option to ask
  2109.       for users' names, telling Sparkle to SET an environment variable
  2110.       called USERNAME.  Later in your batch file, you could refer to
  2111.       users by name like this:
  2112.  
  2113.              Echo  Thank you %USERNAME% for considering our product.
  2114.  
  2115.       DOS would replace %USERNAME% with the name they entered earlier.
  2116.                                                                        
  2117.  
  2118.  
  2119.                          Option 13:  DOS Version                   SS.23
  2120.       ==================================================================
  2121.  
  2122.          Syntax:  SS  13
  2123.  
  2124.  
  2125.         Purpose:  Determine which version of DOS is being used.  This
  2126.                   can be useful to determine if an early versions of DOS
  2127.                   is being used -- a version which won't allow you to do
  2128.                   things later versions allow (like setting DOS environ-
  2129.                   ment variables, as you might when using Sparkle's Get
  2130.                   Input option).
  2131.  
  2132.  
  2133.       IMPORTANT:  This option takes no parameters.  It simply returns
  2134.                   a DOS Errorlevel indicating which version of DOS
  2135.                   currently being used.
  2136.  
  2137.                   The number (errorlevel) will be a 2-digit number
  2138.                   indicating the MAJOR and MINOR parts of the DOS
  2139.                   version.  For example, if you're using DOS 4.1,
  2140.                   Sparkle returns an Errorlevel of 41.  DOS 5.0
  2141.                   would be returned as 50.
  2142.  
  2143.  
  2144.       To Use it:  SS 13      (that's it; no parameters)
  2145.  
  2146.  
  2147.                    In your batch files, test the Errorlevel like this:
  2148.  
  2149.                    If Errorlevel 60 goto ....    ::DOS 6.x or HIGHER
  2150.                    If Errorlevel 50 goto ....    ::DOS 5.x or HIGHER
  2151.                    If Errorlevel 40 goto ....    ::DOS 4.x or HIGHER
  2152.                    If Errorlevel 30 goto ....    ::DOS 3.x or HIGHER
  2153.                    Goto WrongDOS                 ::DOS 2.x of LOWER is
  2154.                                                  ::being used
  2155.  
  2156.  
  2157.                    Note we test Errorlevels from HIGH to LOW!  This is
  2158.                    required by DOS.  See "A Note on Testing Errorlevels"
  2159.                    for more on this.
  2160.                                                                        
  2161.  
  2162.  
  2163.                          Option 14:   VIEW FILE                    SS.24
  2164.       ==================================================================
  2165.  
  2166.          Syntax:  SS  14  TopRow LeftCol BotRow RightCol Color /Name
  2167.  
  2168.         Purpose:  Display ASCII text files in any color in a "window"
  2169.                   on your screen.  The "window" can be any size -- from
  2170.                   the full screen, to just part of it.  Run Demo.Bat to
  2171.                   see an example of displaying files in a partial window.
  2172.  
  2173.       To Use it:  SS 14 TopRow LeftCol BotRow RightCol Color /Name
  2174.  
  2175.                     - "14" = Option #14 (View File)
  2176.  
  2177.                     - "TopRow LeftCol BotRow RightCol" indicate where
  2178.                       on your screen we should display the file.
  2179.  
  2180.                       The top left corner of your screen would be row
  2181.                       1, column 1.  The bottom right corner of 25-line
  2182.                       screens would be 25, 80.
  2183.  
  2184.                     - "Color" is a number from 1 to 128 indicating what
  2185.                       color we should use to display text.  While this
  2186.                       could be greater than 128 for blinking colors, it
  2187.                       might be unkind to expect folks to read screens
  2188.                       full of blinking text.
  2189.  
  2190.                     - "/Name" is the name of the file to display.  BE
  2191.                       SURE to include the drive/directory if your file
  2192.                       is NOT on the current path.
  2193.  
  2194.  
  2195.           Notes:  * YOU must verify your file exists before using this
  2196.                     option.  You'd do that in batch files like this:
  2197.  
  2198.                       If not exist FileName.Ext goto ErrorSection
  2199.                       SS 14 30 25 75 27 /FileName.Ext
  2200.  
  2201.                   * It's also up to YOU to tell users what to do once we
  2202.                     display the file.  Normally, you'd display an "in-
  2203.                     struction screen", then ask Sparkle to display your
  2204.                     file inside some window of that instruction screen.
  2205.  
  2206.                      - Cursor pad keys (Home/End, Left/Right/Up/Down,
  2207.                        PgDn/PgUp) work as they do in most word processors.
  2208.  
  2209.                      - Press ESCAPE to exit View File and move on.
  2210.  
  2211.                   * Only 3 errors are likely to occur.  And Sparkle sets
  2212.                     the DOS Errorlevel to let you know what happened:
  2213.  
  2214.                          0 = No error
  2215.                          1 = File not found
  2216.                          2 = Too little memory (about 5k is required)
  2217.                          3 = A Row, Column or Color number was LESS than 1
  2218.                                                                        
  2219.  
  2220.  
  2221.                      Option 15:   DYNAMIC PROMPTS                  SS.25
  2222.       ==================================================================
  2223.  
  2224.          Syntax:  SS  15 Row Column Color # ("#" = 1, 2 or 3) /Text
  2225.  
  2226.         Purpose:  Display a dynamic prompt, wait for a keypress, set
  2227.                   the DOS Errorlevel based on the key the user presses.
  2228.  
  2229.       To Use it:  SS  15  Row Column Color #
  2230.  
  2231.                     - "15" = Option #5 (Prompt)
  2232.  
  2233.                     - "Row Column" mean the row and column on the screen
  2234.                       where we should display the prompt.
  2235.  
  2236.                     - "Color" is a number from 1 to 128 indicating what
  2237.                       color we should use to display text.  While this
  2238.                       could be greater than 128 for blinking colors,
  2239.                       these prompts are already dynamic.  But feel free
  2240.                       to try blinking colors.  You could also turn on
  2241.                       bright backgrounds, then use blinking colors.
  2242.  
  2243.                     - "#" indicates which prompt you'd like to use.
  2244.  
  2245.                         1 = A Twirling Baton
  2246.                         2 = An Exploding Button
  2247.                         3 = A Scrolling "Press any key to continue..."
  2248.  
  2249.                     - "/Text" is optional.  If included AND you specify
  2250.                        prompt #3, Sparkle scrolls YOUR text across the
  2251.                        screen -- instead of "Press any key to continue..."
  2252.  
  2253.  
  2254.           Notes:  * If you specify prompt #3 and do NOT include "/Text,"
  2255.                     Sparkle will scroll "Press any key to continue..."
  2256.                     But, if you specify #3 AND you include "/Text,"
  2257.                     Sparkle will scroll YOUR message across the screen.
  2258.  
  2259.                   * "Press any key . . ." is about 35 characters wide.
  2260.  
  2261.                     To CENTER it on the screen, specify COLUMN = 23.
  2262.                     If you specify a COLUMN greater than 45, PART of the
  2263.                     banner will wrap around to the next line!
  2264.  
  2265.                   * When the user presses a key to go on, Sparkle sets
  2266.                     the DOS Errorlevel to tell you which key was pressed.
  2267.  
  2268.                     See "A Note on Testing Errorlevels" below.
  2269.                                                                        
  2270.  
  2271.  
  2272.                      Option 16:  DARK BLUE BACKGROUND COLORS       SS.26
  2273.       ==================================================================
  2274.  
  2275.          Syntax:  SS  16  #   ("#" is 1 (Dark blue ON) or 0 (off))
  2276.  
  2277.         Purpose:  Turn ON (or off) dark blue background colors.
  2278.  
  2279.       To Use it:  SS  16  #
  2280.  
  2281.                     - "16" = Option #16 (Dark Blue Backgrounds)
  2282.  
  2283.                     - "#" is "1" (turn it ON) or "0" (off)
  2284.  
  2285.  
  2286.           Notes:  This option requires a VGA monitor -- nothing will
  2287.                   happen on non-VGA monitors.
  2288.  
  2289.                   You can SAFELY include this option in all batch files.
  2290.                   If Sparkle detects a non-VGA monitor, it ignores this
  2291.                   command -- your PC won't crash.
  2292.  
  2293.                   Many people find it easier to read text printed in
  2294.                   highly contrasting colors.  For example, white on
  2295.                   black, or black on red are often easy to read, while
  2296.                   light cyan on green may not be very readable.
  2297.  
  2298.                   But black backgrounds can get tedious.  That's why
  2299.                   many people switch to blue backgrounds.  But that
  2300.                   also might get a little old after awhile.
  2301.  
  2302.                   Sparkle's Dark Blue background gives you an alternative
  2303.                   to black and normal blue backgrounds.  And since the
  2304.                   background is fairly dark, most colored text is quite
  2305.                   readable.
  2306.  
  2307.                                                                        
  2308.  
  2309.  
  2310.                       Option 17:  BIG! SCROLLING MESSAGES          SS.27
  2311.       ==================================================================
  2312.  
  2313.          Syntax:  SS  17  Color CharacterCode Font #Times / Message /
  2314.  
  2315.         Purpose:  Display a TALL message which SCROLLS across the screen.
  2316.                   NOTE:  Scrolling can be "jittery" on slow or very fast
  2317.                   PCs -- because we have to move so much stuff around
  2318.                   the screen
  2319.  
  2320.       To Use it:  SS  17  Color CharacterCode Font #Times / Message /
  2321.  
  2322.                     - "17" = Option #17 (BIGScroll)
  2323.  
  2324.                     - "Color" is a number from 1 to 128 indicating what
  2325.                       color we should use to display text.  While this
  2326.                       could be greater than 128 to make text blink,
  2327.                       scrolling text is already dynamic.  But feel free
  2328.                       to try blinking colors.  You could also turn on
  2329.                       bright backgrounds, then use blinking colors.
  2330.  
  2331.                     - "CharacterCode" is a number from 1 - 254 indicating
  2332.                       which ASCII character we should use to "build"
  2333.                       each tall character with.  If 0, Sparkle defaults
  2334.                       to ASCII character 178.
  2335.  
  2336.                     - "Font" is the number "1" or "0".
  2337.  
  2338.                        -- "0" selects the normal screen font (the same
  2339.                           one used in Sparkle's Big! Font) in which
  2340.                           characters are 7 - 8 lines tall.
  2341.  
  2342.                        -- "2" selects the a custom Broadway font in
  2343.                           in which characters are 13 - 14 lines tall.
  2344.                           This is the "attention-getting" option.
  2345.  
  2346.                     - "#Times" indicates how many times we should scroll
  2347.                       the message across the screen.  "0" means scroll
  2348.                       CONTINUOUSLY -- we won't stop until you press a key.
  2349.                       This is useful to display messages like "Out to
  2350.                       lunch!  Be back at 1:30!" -or- "The backup is done!"
  2351.  
  2352.                       If a key is pressed at any time, we'll stop scrol-
  2353.                       ling -- but we WON'T clear the screen.  Since you
  2354.                       would normally continue in your batch file, you
  2355.                       can clear the screen (CLS) before proceeding.
  2356.  
  2357.                     - "/ Message /" is the text you want displayed.
  2358.  
  2359.                       NOTE:  "message" can contain almost ANY ASCII char-
  2360.                       acters.  And we URGE YOU to LENGTHEN messages with
  2361.                       blanks so they scroll completely off the screen.  Do
  2362.                       this by adding 8 - 10 SPACES to the end of messages,
  2363.                       followed by "/" (or your "text marker") -- like this:
  2364.  
  2365.                          SS 17 27 219 1 1 / Clear with spaces          /   
  2366.  
  2367.  
  2368.                      Option 18:  FADES (screen transitions)        SS.28
  2369.       ==================================================================
  2370.  
  2371.          Syntax:  SS  18  # (1 - 9) Color Slow_it_down (1 - 20)
  2372.  
  2373.         Purpose:  Clear the screen in dramatic ways, in any color.
  2374.  
  2375.       To Use it:  SS  18  # (1 - 9) Color Slow_it_down (1 - 20)
  2376.  
  2377.                     - "18" = Option #18 (Fades)
  2378.  
  2379.                     - "#" = is a number from 1 - 9 indicating which
  2380.                       screen transition you want to use:
  2381.  
  2382.                       1 = Close In (top/bottom)  2 = Open Out (top/bottom)
  2383.                       3 = Slide Up               4 = Slide Down
  2384.                       5 = Explode out            6 = Vertical Blinds
  2385.                       7 = Columns Up & Down      8 = "Old TV" Shutdown
  2386.                       9 = Wild Spiral
  2387.  
  2388.                     - "Color" is a number from 1 to 128 indicating what
  2389.                       color we should use to clear the screen.  All op-
  2390.                       tions EXCEPT #9 use this color to clear the screen.
  2391.                       #9 (Wild Spiral) uses colors already on the screen.
  2392.  
  2393.                     - "Slow_it_down" is a number from 1 - 20 which lets
  2394.                       you control how fast screen fades occur -- the
  2395.                       higher the number, the slower it will occur.  #9
  2396.                       (Wild Spiral) does NOT use this -- since too much
  2397.                       is happening already.
  2398.  
  2399.  
  2400.           Notes:  We've made each option as fast as possible -- to
  2401.                   give YOU maximum flexibility, and to let YOU fine-
  2402.                   tune these screen effects based on your PC's speed.
  2403.  
  2404.                   But, depending on what colors and text are on the
  2405.                   screen, some fades may be TOO FAST.  No problem, just
  2406.                   use a "slowdown" number of, say, 3 - 5.  A slowdown
  2407.                   number of 15 - 20 is v-e-r-y slow.
  2408.  
  2409.                   Also note that option 9 (Wild Spiral) grabs whatever
  2410.                   exists in column 1 of row 25 and starts spinning that
  2411.                   around the screen.  So you might want to control what
  2412.                   appears in row 25, column 1 BEFORE you use Wild Spiral.
  2413.                   And Wild Spiral does NOT scroll row 25.
  2414.  
  2415.                                                                        
  2416.  
  2417.  
  2418.                  Option 19:  Sparkle's BROADWAY SCREEN FONT        SS.29
  2419.       ==================================================================
  2420.  
  2421.          Syntax:  SS  19  # (1 = load Broadway Font, 0 = use Normal Font)
  2422.  
  2423.         Purpose:  On VGA screens (only) install a tall, Broadway screen
  2424.                   font.  This will appear on text-mode screens only, and
  2425.                   ONLY with text printed in LOW intensity colors.  Text
  2426.                   in HIGH intensity colors will appear in the normal
  2427.                   screen font -- letting you get two text-mode fonts
  2428.                   on the screen at the same time!  Run Demo.Bat and
  2429.                   select the "Menus" option to see an example -- on VGAs.
  2430.  
  2431.       To Use it:  SS  SS  19  # (1 = Broadway Font ON, 0 = Normal Font)
  2432.  
  2433.                     - "19" = Option #19 (Broadway font)
  2434.  
  2435.                     - "#" = is 1 (load the Broadway font), or 0 (Normal)
  2436.  
  2437.           Notes:  Sparkle's Broadway font comes from our FONT PAK utility.
  2438.                   Font Pak (available in both DOS and PROGRAMMERS' ver-
  2439.                   sions) offers about 100 screen fonts, and many utilities.
  2440.  
  2441.                   Many people aren't aware that on EGA or VGA monitors
  2442.                   one can "download" 1 - 8 different fonts, then switch
  2443.                   among them quickly and easily.  You can also display
  2444.                   2 fonts at once on the same screen -- in TEXT mode!
  2445.  
  2446.                   Note that this Broadway font is v-e-r-y TALL -- too
  2447.                   tall for EGA screens.  And because it's so tall, it
  2448.                   is NOT well suited for displaying consecutive lines of
  2449.                   text all in the same Broadway font.  RATHER, it's
  2450.                   better suited for titles, menus or highlighting words
  2451.                   or phrases -- with lines immediately above/below it
  2452.                   either blank, or appearing in the normal font.
  2453.  
  2454.                   Once you load the Broadway font, YOU determine what
  2455.                   text appears in the Broadway font, and what appears
  2456.                   in the normal font.  You do this by controlling the
  2457.                   INTENSITY of the color(s) you use to display text.
  2458.  
  2459.                    * Any text appearing in LOW intensity colors will
  2460.                      appear in the Broadway font.  Text in HIGH
  2461.                      intensity colors appears in the normal font.
  2462.  
  2463.                    * Several Sparkle options let you print things in
  2464.                      colors you prefer (or change the colors of text):
  2465.                      Windows, Quick_Print, Paint and Reverse Colors.
  2466.  
  2467.                   NOTE:  For an interesting effect, load the Broadway
  2468.                   font, display some text, then alternately PAINT that
  2469.                   text with Low, then High intensity colors -- pausing
  2470.                   briefly in between.  As you paint it, the text will
  2471.                   switch from the Broadway to the normal font.
  2472.                                                                      
  2473.  
  2474.  
  2475.                 APPENDIX I:  A Note on Testing Errorlevels           A.1
  2476.       ==================================================================
  2477.       Also see APPENDIX III:  ASCII Codes for many keyboard characters.
  2478.  
  2479.       Always test Errorlevels from the HIGHEST number to the LOWEST.
  2480.       This is a DOS restriction.  For example:
  2481.              If Errorlevel 2 goto no         \   this sequence
  2482.              If Errorlevel 1 goto yes        /   is correct
  2483.  
  2484.              If Errorlevel 1 goto yes        \   this sequence
  2485.              If Errorlevel 2 goto no         /   is WRONG
  2486.  
  2487.       Here's why this is important.  DOS tests the phrase:
  2488.  
  2489.                     If Errorlevel 1 goto yes
  2490.  
  2491.       as if it read "If Errorlevel greater-than-or-equal-to-1 goto Yes."
  2492.  
  2493.       So, if you start testing with "If Errorlevel 1 goto Yes" (note
  2494.       "1"), DOS will almost ALWAYS go to "Yes" -- since most everything
  2495.       is "greater-than-or-equal-to 1".
  2496.  
  2497.       Examples:
  2498.       =========
  2499.  
  2500.       For example, here's how you might test errorlevels after getting
  2501.       a choice from a scrolling bar menu.
  2502.  
  2503.       Note that we first test for Escape (Ascii code 27).  Bar menus
  2504.       return the NUMBER of the option chosen.  Suppose this menu had 5
  2505.       choices.  We first test for Escape, since 27 is higher than 5.  We
  2506.       then test for which option was chosen with "If Errorlevel 5 ...."
  2507.  
  2508.           :_MainMenu
  2509.           SS  2  5 5 5 76 112 2
  2510.           If Errorlevel 27 goto _End
  2511.           If Errorlevel 5  goto _End
  2512.           If Errorlevel 4  goto _BarMenus
  2513.           If Errorlevel 3  goto _Sounds
  2514.           If Errorlevel 2  goto _Windows
  2515.           If Errorlevel 1  goto _Intro
  2516.           goto _MainMenu                   (just in case tests fail)
  2517.  
  2518.       Here's what a batch file might look like if you used ASK.
  2519.  
  2520.         * NOTE:  Here we test for Escape LAST!!  That's because ASK
  2521.           returns the ASCII value of the UPPER CASE key pressed.  The
  2522.           ASCII code for "Y" is 89, the code for "N" is 78.  The code
  2523.           for Escape (27) is LESS THAN 89 or 78, so we test for it last.
  2524.  
  2525.           :_AskAgain
  2526.           SS 3 25 20 112 /YN /Do you want to go on?  Press [Y]es or [N]o
  2527.           If Errorlevel 89 goto _YesPressed
  2528.           If Errorlevel 78 goto _NoPressed
  2529.           If Errorlevel 27 goto _AskAgain     '--- We'll ONLY accept Y or N!
  2530.           goto _AskAgain                      '--- Ditto for any other key.
  2531.                                                                        
  2532.  
  2533.  
  2534.                     APPENDIX II:  Choosing COLOR NUMBERS             A.2
  2535.       ==================================================================
  2536.  
  2537.       Several Sparkle options ask for a COLOR NUMBER:  ONE number indi-
  2538.       cating BOTH Foreground AND Background colors.  Here's how to
  2539.       determine it.  (Tip:  Print this page as a quick reference guide.)
  2540.  
  2541.       Step 1:  In the table below, move your finger DOWN the left column
  2542.                until it's on the FOREGROUND color you want.  Notice that
  2543.                the first 8 colors are "normal" (low) intensity, the next
  2544.                8 are "bright" ("high intensity") versions of the first 8.
  2545.  
  2546.       Step 2:  Now move your finger ACROSS the columns until it's under
  2547.                the BACKGROUND color you want.  Use the number you see
  2548.                there (under your finger).  NOTE that, as you move across
  2549.                the columns, numbers increase by 16.  If you prefer for-
  2550.                mulas to tables:  Color = ForeGround + (Background * 16).
  2551.                Foreground colors range from 0 - 15; Background from 0 - 7.
  2552.  
  2553.       Step 3:  OPTIONAL:  For blinking -OR- bright background colors,
  2554.                add 128 to the number you got in step 2.  If you want
  2555.                bright background colors, BE SURE to first use Sparkle's
  2556.                option to turn Bright_BG colors ON.
  2557.  
  2558.                                    BACKGROUND COLORS
  2559.                                    =================
  2560.  
  2561.                     Black  Blue Green  Cyan  Red Magnta Brown White
  2562.                    ---0-----1-----2-----3-----4-----5-----6-----7----
  2563.  
  2564.        F    Black     0    16    32    48    64    80     96   112
  2565.        O    Blue      1    17    33    49    65    81     97   113   N
  2566.        R    Green     2    18    34    50    66    82     98   114   O
  2567.        E    Cyan      3    19    35    51    67    83     99   115   R
  2568.        G    Red       4    20    36    52    68    84    100   116   M
  2569.        R    Magenta   5    21    37    53    69    85    101   117   A
  2570.        O    Brown     6    22    38    54    70    86    102   118   L
  2571.        U    White     7    23    39    55    71    87    103   119
  2572.        N
  2573.        D    Grey      8    24    40    56    72    88    104   120
  2574.             Blue      9    25    41    57    73    89    105   121   B
  2575.        C    Green    10    26    42    58    74    90    106   122   R
  2576.        O    Cyan     11    27    43    59    75    91    107   123   I
  2577.        L    Red      12    28    44    60    76    92    108   124   G
  2578.        O    Magenta  13    29    45    61    77    93    109   125   H
  2579.        R    Yellow   14    30    46    62    78    94    110   126   T
  2580.        S    White    15    31    47    63    79    95    111   127
  2581.  
  2582.       For Example:
  2583.       ============
  2584.              Any color on black background:     1 - 15
  2585.       Black foreground on white background:      112   (visible on any monitor)
  2586.          Bright white on a blue background:       31
  2587.                  Black on a red background:       64
  2588.        Blinking black on a cyan background:      176   (48 + 128 = 176)
  2589.  
  2590.                                                                        
  2591.  
  2592.         
  2593.           APPENDIX III:  ASCII Codes for many keyboard characters    A.3
  2594.       ==================================================================
  2595.  
  2596.        Use the chart below to help add "If Errorlevel # ...." statements
  2597.        to your batch files.
  2598.  
  2599.        When you use several of Sparkle's options (like Ask and Prompt),
  2600.        Sparkle sets the DOS Errorlevel to let you know which key users
  2601.        pressed.  The chart below lists the ASCII values for most key-
  2602.        board characters.  Note:
  2603.  
  2604.         * We list ASCII values of just UPPER CASE letters.  Lower
  2605.           case letters have values 32 higher than those shown.
  2606.  
  2607.         * Remember to test errorlevels from HIGH to LOW.  Appendix I,
  2608.           "A Note on Testing Errorlevels," explains why.
  2609.  
  2610.                             ASCII                          ASCII
  2611.              Key Pressed    Code             Key Pressed   Code
  2612.              ===========    =====            ===========   =====
  2613.                   A           65                  B          66
  2614.                   C           67                  D          68
  2615.                   E           69                  F          70
  2616.                   G           71                  H          72
  2617.                   I           73                  J          74
  2618.                   K           75                  L          76
  2619.                   M           77                  N          78
  2620.                   O           79                  P          80
  2621.                   Q           81                  R          82
  2622.                   S           83                  T          84
  2623.                   U           85                  V          86
  2624.                   W           87                  X          88
  2625.                   Y           89                  Z          90
  2626.  
  2627.                   0           48                  1          49
  2628.                   2           50                  3          51
  2629.                   4           52                  5          53
  2630.                   6           54                  7          55
  2631.                   8           56                  9          57
  2632.                                                                    
  2633.  
  2634.      ===============================================================
  2635.                           To Register or Order
  2636.      ===============================================================
  2637.  
  2638.      Because we offer so many programs, our order form has 2 pages.
  2639.  
  2640.       * THIS PAGE lists our programs and the per-copy cost of each.
  2641.         Please read CATALOG.Txt for a description of each program.
  2642.  
  2643.       * THE NEXT PAGE is the actual order form.
  2644.  
  2645.         - On the next page, fill in the name of each program you're
  2646.           ordering.  PLEASE BE CAREFUL here and use the names listed
  2647.           below.  If we're not sure which program you're ordering,
  2648.           we may have to return you're order.
  2649.  
  2650.         - If ordering by Visa or MasterCard, fill in the section
  2651.           for credit card orders.  BE SURE TO SIGN it.
  2652.  
  2653.        Program Name                                          Per Copy
  2654.        ==============================================================
  2655.        Multi-Print      $19 if ordered w/ ANY other program  $19/$29
  2656.  
  2657.        Font Pak "Pro"   Programmer's Fonts & Mouse Shapes      $49
  2658.  
  2659.        Font Pak "DOS"   Hundreds of DOS text-mode fonts        $29
  2660.  
  2661.        PDT              The Pro~Formance Data Tool            $139
  2662.        PDT Tool Kit     (FREE when you order PDT!)             $39
  2663.  
  2664.        inform-Z         Professional Forms Design              $29
  2665.  
  2666.        Mail Call        With MC Express                        $29
  2667.  
  2668.        Pro~Scribe & PS Express                                 $29
  2669.  
  2670.        P~F Presents     Professional Version                   $79
  2671.  
  2672.        P-Screen Professional                                   $49
  2673.            "    Plus                                           $29
  2674.  
  2675.        Pro~Stamp        Stamp Collection Manager               $29
  2676.  
  2677.        Ram-Man          RAM-resident Text File Browser         $19
  2678.  
  2679.        Sparkle AND Menu Magic                                  $29
  2680.  
  2681.        The Survey Catalyst                                    $395
  2682.  
  2683.      =================================================================
  2684.      PACKAGE DISCOUNTS  Call about quantity discounts & site licenses.
  2685.      =================================================================
  2686.        THE WORKS!  One of each program (except The Catalyst)  $299
  2687.        Sparkle -AND- P-Screen                                  $49
  2688.        inform-Z -AND- Mail Call                                $49
  2689.        P-Screen Pro -AND- P~F Presents (Pro versions of both)  $99
  2690.                                                                      
  2691.  
  2692.  
  2693.      ============================= TO  ORDER  =============================
  2694.  
  2695.      For FASTEST delivery of your programs, CALL with a Visa/MC card number.
  2696.  
  2697.  
  2698.      F __________________________________________   M    Rob W. Smetana
  2699.                                                          Pro~Formance
  2700.      R __________________________________________   A T  132 Alpine Terrace
  2701.                                                          San Francisco, CA
  2702.      O __________________________________________   I O      94117
  2703.                                                          (415) 863-0530
  2704.      M __________________________________________   L
  2705.                                                          Make checks payable
  2706.      Phone (     ) ______-________ Date ___/___/___      to:  Rob W. Smetana
  2707.  
  2708.      =======================================================================
  2709.                            For Visa or MasterCard Orders
  2710.      =======================================================================
  2711.  
  2712.      Credit Card Number:  ________________________________  Expires: ___|___
  2713.  
  2714.      Signature (Required for credit card orders): __________________________
  2715.  
  2716.      Be sure your name at the top matches how it appears on your credit card.
  2717.  
  2718.      ============================================================= spk 4.2 =
  2719.  
  2720.      Name of Program or "Package"         # of Copies  Price/Copy    Total
  2721.  
  2722.      =======================================================================
  2723.  
  2724.      Multi-Print ($19 if ordered /w other pgm) _____  x  $19/$29 =  $_______
  2725.  
  2726.      _____________________________________  ________  x  ______  =  $_______
  2727.  
  2728.      _____________________________________  ________  x  ______  =  $_______
  2729.  
  2730.      =======================================================================
  2731.  
  2732.      Shipping & Handling: Total Number
  2733.      of Programs (and Copies)  ----->>   _____@ $4/copy             $ ______
  2734.      =============================+=========================================
  2735.                                   |                     Subtotal  $ ________
  2736.       INTERNATIONAL ORDERS: : :   |
  2737.                                   |    CA. residents, add 8.5% tax $ _______
  2738.       * US funds only please.     +-----------------------+-----------------
  2739.       * Money order, check drawn a                        |
  2740.         US bank, or VISA/MasterCard                       |TOTAL  $ ________
  2741.      =====================================================+=================
  2742.  
  2743.      WHERE did you got your copy of our program? _________________________
  2744.      This helps us learn the best way to get new programs to you.  And feel
  2745.      free to write comments and suggestions on the other side.   Thank you.
  2746.  
  2747.